hivelore

Hivelore

エージェントが書いたコードに対する決定論的なポリシーゲート — チームがすでに代償を払ったミスを繰り返すコミットを拒否します。
コーディングエージェントのハーネス向けに、リポジトリに組み込まれたコンテキストポリシーを提供します。ルールはチームの記憶として保存されます。以前は hAIve（@hiveai/*）として公開されていました。

Hivelore は、AI コーディングエージェントのハーネスにおける強制レイヤーです。エージェントが作業を始める前にチーム固有の自明ではない知識を伝え、苦労して得た教訓を MCP、Git フック、CI における決定論的なゲートに変え、同じミスを繰り返そうとする変更をブロックします。同じ差分なら、どのマシンでも同じ判定になります。記憶は基盤であり、ゲートが製品です。

高性能なモデルは、一般的なベストプラクティスをすでに把握しています。しかし、チーム固有でリポジトリに依存する恣意的な知識までは推測できません。たとえば、公開 ID は id + 100000 の先頭に AC- を付けること、ステータスフィールドは "OK"／"KO" でなければならないこと、適用済みのマイグレーションは決して編集しないことです。何も手を加えなければ、自信満々のエージェントが、もっともらしい答えを作り出します。きれいで、テスト済みで、問題なく動くものの、ポリシーには違反しています。Hivelore は、推測できないその知識を作業に引き継ぎ、違反しようとしている変更をブロックします。

Hivelore の役割は、テスト、リンター、オブザーバビリティを置き換えることではありません。これらのツールでは推測できない、リポジトリ固有の知識を利用可能かつ監査可能にし、強制できるようにします。

_{ミスを記録 → 検証済みのガードを適用 → 同じミスを繰り返すコミットを拒否。 どのマシンでも、CI でも、同じ差分には同じ判定を返します。60 秒で再現する ↓}

---

問題

AI コーディングエージェントは強力ですが、リポジトリのコンテキストが不十分なまま動作することがよくあります。コンテキストの圧縮、並行セッション、エージェントの切り替え、古くなった参考ドキュメントは、いずれも同じ失敗を招きます。エージェントがチームの最新の決定を作業に引き継がずにコードを変更してしまうのです。

多くのチームは、指示を出して期待することで、この問題に対処しています。

• 「まず、アーキテクチャ上の決定事項を読んでください。」
• 「前のスプリントで起きたマイグレーションのミスを繰り返さないでください。」
• 「学んだことを記録するのを忘れないでください。」
• 「チームの決定を無効にするコードをマージしないでください。」

こうしたルールは簡単に見落とされます。Hivelore は、ルールをリポジトリに組み込まれたコンテキストポリシーに変えます。

---

仕組み

AI agent ──▶ Hivelore briefing ──▶ code change ──▶ Hivelore policy gate ──▶ merge
                  ▲                                       │
                  └── context breadcrumbs · decisions · gotchas · anchors

1. hivelore init は、リポジトリに .ai/ コンテキストポリシーレイヤーを作成します。
2. エージェントは、各セッションの開始時に get_briefing を実行します。これは、少量のデフォルトコンテキストと、タスクとの関連性に基づいて順位付けされた、さらに詳しい手がかりを返す MCP 呼び出しです。
3. 決定事項、注意点、失敗した試み、セッションの要約は、それらが説明するコードパスに紐付けられた Markdown ファイルに保存されます。コードの場所が変わると、Hivelore は古くなったアンカーを検出します。
4. hivelore enforce check と CI による強制適用は、ブリーフィングの欠落、重要な決定事項の古さ、差分によって繰り返されようとしているアンチパターンのアンカー、または記録されていないセッションの知識といった危険な状態を阻止します。

メモリは基盤です。コンテキストの強制適用が製品の約束です。 チームの最新の知識を参照せずに、AI による変更がコードベースに入ることはありません。

9 月 18 日のクライアント報告を受けた変更について、エビデンスの確認、より簡潔なブリーフィング、タスク単位での完了を含む詳細は、実装ノートをご覧ください。

ハーネスにおける Hivelore の位置付け

ハーネスエンジニアリングとは、モデルを取り巻く環境を整えることです。モデルが行動する前に提供するフィードフォワードのガイダンス、行動した後のフィードバックセンサー、そして不適切な状態の反映を防ぐワークフローゲートが含まれます。Hivelore は、そのハーネスの リポジトリ固有のコンテキストポリシー を担います。

ハーネスの関心事	Hivelore の役割
フィードフォワードのガイダンス	get_briefing、モジュールコンテキスト、スキル、決定事項、注意点、失敗した試み
フィードバックとゲート	MCP の順序付けポリシー、pre_commit_check、Git フック、CI による強制適用、古いアンカーの検出
知識のライフサイクル	Git ネイティブな Markdown 記録、パス／シンボルのアンカー、確信度、廃止、リンティング
境界	Hivelore は単体テスト／E2E テスト、型チェック、ランタイムトレース、セキュリティスキャナー、LLM 評価を補完しますが、これらに取って代わろうとはしません

このように対象を絞っているのは意図的です。Hivelore は汎用メモリデータベースでもエージェントダッシュボードでもありません。コーディングエージェントが、チームの検証済みで自明ではない知識を活用して行動できるよう支援する制御レイヤーです。

範囲と境界 — 3 つのハーネス

ハーネスエンジニアリングでは、エージェントが書いたコードの 3 つの異なる側面を管理します。Hivelore が意図的に扱うのはそのうち 2 つで、残りの 1 つは現時点では対象外としています。

ハーネスの側面	答える問い	現時点の Hivelore
保守性	コードはクリーンか？（パターン、落とし穴、規約）	✅ 対応済み — 実行可能なセンサー ＋ アンチパターンゲート
アーキテクチャの適合性	チームの構造上の決定を尊重しているか？	🟡 一部対応 — アンカー付きの decision／architecture メモリ ＋ 決定事項の網羅性ゲート
振る舞い	コードは 機能的に正しい 動作をするか？	🟡 橋渡し — コマンドセンサーが独自のテストをレッスンに結び付けます（以下を参照）

振る舞いのハーネスがまだない理由。 機能的な正しさの検証には オラクル、つまりコードが どう動作すべきか を示す独立した真実の情報源が必要です。このオラクルの問題は、エージェントが自分の成果を採点するという落とし穴とともに、この分野で最も成熟していない部分です。この領域を担うのは、皆さんのテスト、プロパティベースのチェック、LLM 評価です。Hivelore はこれらに取って代わろうとはしません。Hivelore が担うのは、振る舞いのテストで別途エンコードしなければならない 推測できない意図（status must be OK/KO、public ids = id + 100000）を、フィードフォワードのコンテキストと決定論的なセンサーとして伝えることです。これは振る舞い制御の部分的かつ静的な一側面であり、ランタイムの機能オラクルではありません。

橋渡しとなる機能を提供しています（v0.33.0）：コマンドセンサー。 レッスンには正規表現の代わりに コマンド（独自のテストまたは不変条件スクリプト）を設定できます。差分がセンサーの対象パスに触れると、ゲートがそのコマンドを実行し、終了コードがゼロ以外の場合は、レッスンをメッセージとしてコミットを拒否します。Hivelore はオラクル（未解決の問題）を作り出すのではなく、チームがすでに管理しているオラクルを、それが保護するレッスンに結び付けます。

hivelore memory tried \
  --what "refund exceeded the captured amount" \
  --why-failed "prod incident #442 — refunds must clamp to capture" \
  --paths src/payments/ \
  --sensor-command "npx vitest run tests/payments/refund-invariants.spec.ts"
# → validated (the oracle must PASS on the current tree), then enforced at commit + CI
#   Saved team-scoped by default: an enforced lesson must travel to every machine and CI.

誠実さを保つルール：リポジトリごとにオプトインします（enforcement.runCommandSensors: true — リポジトリ内で作成されたコマンドを実行します）。正しいはずのツリーでオラクルが失敗する提案は却下されます。また、オラクルがまだ保留中のスタブである場合、ブロックセンサーを有効化できません。実行できないコマンド（見つからない、タイムアウトする）は警告を出しますが、ブロックはしません。壊れたハーネスをテスト失敗に見せかけてはいけません。コマンドはサニタイズされた環境で実行されます（テストランナーに必要な基本環境のみで、クラウド認証情報やトークンは含みません）。保証を実証可能にすることもできます。--red-ref <pre-fix-commit> はスクラッチのワークツリーでインシデントを再現し、そこでオラクルが失敗することを要求します。センサーはその後、red_proven: true を記録し、防止レシートに表示します。クラッシュはREDではありません。インシデントの状態でアサーションに到達する前にオラクルがエラーになった場合（ガード対象のコードがまだ存在しない、インポートエラーや構文エラー、「テストが見つかりません」など）、再現結果は red-unrunnable となり、証明済みとは認められません。動作の完全な検証（テスト生成、LLM 評価）は、引き続きテストスイートで行います。

v0.43.0 以降、ブロックするシェル／テストセンサーでは prove-RED が必須です。再現可能なインシデント状態がないオラクルは warn のままになります。CI では commandSensorUnrunnable: "block" を設定して、必須のオラクルがない場合にハーネスの不具合として失敗させることもできます。また、sensorWeakeningGate: "block" を設定すると、保護がひそかに格下げまたは削除されるのを防げます。

導入の第一歩（v0.36.0）：インシデントからテストをひな形生成します。 コマンドセンサーで検査するにはテストが必要です。そのため、Hivelore は教訓からひな形を生成します。hivelore sensors scaffold <memory-id>（または scaffold_test MCP ツールを使えば、エージェントがセッション中に実行できます）はテストフレームワーク（vitest／jest／pytest／go）を検出し、インシデントの来歴をヘッダーに記載した保留中のテストを書き込み、センサーを有効化する正確な sensors propose --kind test コマンドを表示します。センサー自体を有効化することはありません（検証済みの唯一の書き込み手段は引き続き propose_sensor です）。アサーションを書くまではスタブが保留状態のままなので、スイートは成功します。モノレポでは、フレームワークと配置先はリポジトリのルートではなく、教訓のアンカーパスを所有するパッケージから決まります（packages/api/ 以下の教訓は packages/api/tests/… にひな形が生成されます）。また、教訓が複数のパッケージにまたがる場合は、所有する各パッケージに保留中のテストが1つずつ生成され、各テストの実行コマンドを連結する1つのセンサーで有効化されます。ひな形が保留のまま、または有効化されないままの場合は未完了の作業として扱われ、オラクルが割り当てられるまで doctor と enforce finish が post-incident-test-unarmed で通知します。

インシデントを渡すと、修正をもとにスタブを生成します（v0.46.0）。 --red-ref <pre-fix-commit> を追加すると、ひな形は修正によって red_ref..HEAD で実際に変更されたシンボルを特定し、それらを使って例をあらかじめ記入します。空の subjectUnderTest() ではなく、import { refund } …、expect(refund(/* incident input */)).toBe(/* post-fix expected */) のような形になります。これは保留中のコメント付きスタブのままです（ライブインポートはなく、スイートは成功します）。LLM にアサーションを推測させるのではなく、決定論的に作業を始めやすくするものです。

hivelore sensors scaffold 2026-07-03-attempt-refund-exceeds-capture --red-ref <pre-fix-commit>
# → tests/incidents/refund-exceeds-capture.test.ts (pending; names the touched symbols from the fix)
#   then: fill the assertion → run it → arm it with the printed propose command.

不変条件を表現する手間を減らします（v0.48.0）：--style。 動作検証ハーネスでは、オラクルは自分で用意します。そのため、アサーションをLLMに推測させることなく、ひな形から決定論的に手間を減らす2つの方法を選べます。

• --style property — fast-check／Hypothesis のひな形です。不変条件を一度だけ記述すると（refund(a, b) ≤ b）、多数の生成入力に対して検証されます。
• --style differential --reference <impl> — 不変条件を一切記述せず、対象がすべての生成入力に対して参照実装（旧バージョンや別の実装）と一致することをアサートします。

hivelore sensors scaffold <lesson> --red-ref <pre-fix-commit> --style property
hivelore sensors scaffold <lesson> --style differential --reference ../legacy/refund

どちらも保留中のコメント付きスタブのまま（スイートは成功します）で、内容を記入した後は、同じ検証済みの prove-RED 手順で有効化します。 動作ハーネスを測定します（v0.45.0）。 hivelore doctor は、主要なコード領域ごとに、動作面がどの程度ガードされているかを報告します。Behaviour harness: X/N area(s) guarded by a behavioural oracle (K armed, P red-proven) と表示されるため、ブランチの進捗を推測ではなく確認できます。人間向けの stats receipt にも、同じ行がフッターとして表示されます。v0.47.0 以降、この検出結果から次のアクションまでつながります。未カバーの領域ごとに、Suggested commands に正確な hivelore sensors scaffold <lesson> --red-ref <pre-fix-commit> コマンドが表示されます（レッスンがまだない場合は、memory tried … then scaffold の行が表示されます）。

1.0 の凍結されたサーフェスについては STABILITY.md を、Hivelore の拡張については CONTRIBUTING.md を参照してください。

実行可能なメモリーセンサー

一部の gotcha および attempt メモリーに sensor ブロックを追加できるようになりました。これは差分をスキャンする決定論的なガードレールです。形式は3種類ですが、検証方針は共通です（正しいコードでは何も起こらず、誤りがあると検出します）。

• regex — 追加された行に対して照合します。シンプルで依存関係のないデフォルトです。
• ast — ast-grep の構造パターンです（stripe.paymentIntents.create($$$) に absent: idempotencyKey を指定）。コメントや文字列リテラルによる誤検出はなく、「Y を伴わない X」は呼び出し自体に対して表現できます。オプションの @ast-grep/napi エンジンが必要です。エンジンがない場合、センサーは実行できず、警告のみでブロックはしません。
• shell/test — 独自のテストをオラクルとして実行するコマンドです（後述の動作ブリッジ）。

センサーによって、文書化されたレッスンを、埋め込みやモデルの判断に依存しない、繰り返し利用可能なフィードバックシグナルにできます。自動生成されたセンサーは warn から始まり、人間が検証済みのものを block に昇格させます。この方針は逆転に対しても適用されます。レッスンで推奨されている修正（Instead, use: のスニペット）に一致する block パターンは拒否されます（fires-on-correct）。正しいコードをブロックし、誤りを検出できなくなるためです。

hivelore sensors list
hivelore sensors check                          # scans git diff --cached
hivelore sensors propose <lesson> --from-fix <pre-fix-ref>   # MINE the pattern from the fix diff
hivelore sensors promote <id> --yes             # promote a vetted sensor to block
hivelore sensors export --format grep

より低コストな有効化（--from-fix）。 文書化されたレッスンを強制適用可能にするまでの主なコストは、誤りを識別する正規表現の作成です。そのため、修正からパターンを作成できるようにします。sensors propose --from-fix <pre-fix-ref> は修正差分からパターンを抽出します。修正で削除された行が誤り（pattern）、追加された行が正しいことを示すマーカー（absent）になります。正規表現を自分で作成する代わりに候補を確認できます。ブロック可能になる前には、完全な検証（現在のコードでは何も起こらない、誤りがあると検出する、逆転していない）にも引き続き合格する必要があります。

---

インストール

npm install -g @hivelore/cli
# Optional: local semantic search (downloads ~110MB model once)
npm install -g @hivelore/embeddings

---

統合全体を検証する

hivelore agent check --exercise --json を実行すると、隔離された一時リポジトリ内で、MCP ブリーフィング、対象を絞ったフックコンテキスト、ならびに正しいコードと誤ったコードを使った検証済みセンサーをテストできます。また、初回編集までの遅延と、読み取り、繰り返しの編集、シェル呼び出しについて、10サンプルの中央値と p95 の所要時間も報告されます。これは合成的なインストール検証であり、生産性ベンチマークではありません。 新しいプロジェクトでは、ローカルでのタスク完了と下書きの記録がデフォルトになります。既存のポリシーは維持されます。 監査での修正とアップグレードガイドを参照してください。

アップグレード後、hivelore agent setup --no-global を実行して、管理対象の古い Git フックを修復してから、AI クライアントを再起動してください。新たに正常なハンドシェイクが行われても、実行中の会話はアップグレードされません。 hivelore agent check --json では、既知の稼働中の MCP バージョンと残っている移行作業を一覧表示します。 古い CI ワークフローには、レビュー用の置き換え候補 .candidate が作成されます。カスタムフックコマンドは保持されます。

完全なポリシーと追跡可能な結果

編集前に、適用可能な短いポリシーが挿入されます。ポリシーが収まりきらない場合、フックは例外を黙って省略するのではなく、明示的な 指示未配信 の参照先を出力します。不完全なブリーフィングは、完全な確認とはみなされません。フックの session_id を指定して mem_get を使うか、hivelore memory get <id> --session-id <session> を実行して、ポリシー全体を読み、参照してください。

mem_feedback はデフォルトの MCP プロファイルで利用できます。コミット、テストレポート、またはインシデントの reference とともに、applied／rejected、または corrected／verified を報告してください。任意の catch_id を指定すると、フィードバックを hivelore stats outcomes に記載されたインターセプトに関連付けられます。関連付けられた検証には、その前に修正が必要です。レポートでは、申告された結果と、その後に観測されたサイレントなセンサーチェックを区別します。参照先を認証したり、回避できたバグや節約できた時間を推測したりするものではありません。

ベンチマークレポートが decision-ready と認定されるには、10 件以上の異なるタスク × 3 回の反復、比較可能なモデル、チェックアウト、予算、プロンプトのメタデータ、独立した評価の証明、および一致する protocol.json／run.json マニフェストが必要です。1 つのタスクを繰り返したり、アームを削除したりしても、準備済みのプロトコル要件を満たすことはできません。この評価が示すのは証拠の完全性であり、優位性が証明されたことや、実行が認証されたことではありません。

60 秒でわかる証明 — レッスンがコミットを阻止する様子を見る

これは上記のデモで紹介した正確なフローです。

メモリツールは情報を記憶します。Hivelore の違いは、記憶したレッスンによって、それを繰り返すコミットを拒否できることです。任意の git リポジトリで試してみてください。

hivelore init -y                     # .ai/ layer + git hooks + bridges for the agents you actually use (detected)

# 1. Capture a failed approach (agents do this via the mem_tried MCP tool)
hivelore memory tried \
  --what "importing moment.js" \
  --why-failed "bundle bloat — team standard is date-fns" \
  --instead "date-fns" --paths src/
#    → prints the new memory id, e.g. 2026-07-02-attempt-importing-momentjs

# 2. Give the lesson teeth: a validated, deterministic guardrail
hivelore sensors propose 2026-07-02-attempt-importing-momentjs \
  --pattern "from ['\"]moment['\"]" --severity block
#    Hivelore validates it first: silent on your current code, fires on the mistake.

# 3. Reintroduce the mistake — the commit is refused
echo "import moment from 'moment';" >> src/dates.ts
git add . && git commit -m "add date helper"
#    🛡️  A documented lesson refused this commit — about the change you just made:
#        • 2026-07-02-attempt-importing-momentjs (src/dates.ts)  use date-fns
#          import moment from 'moment';

同じ差分、同じ回答が、どのマシンでも CI でも適用されます。ゲートは意図的に決定論的です。すべてが .ai/ 内のレビュー可能な Markdown として保存され、コードとともにバージョン管理されます。rm -rf .ai を実行すれば、すべて元に戻せます。

---

クイックスタート

1. プロジェクトを初期化する

cd my-project
hivelore init          # Creates .ai/, bridge files, MCP config, hooks, CI template

hivelore init は、エージェントのセットアップも実行するようになりました。プロジェクトレベルの MCP 設定を書き込み、利用可能な最適なモードを記録し、ユーザーレベルのクライアント設定を変更する前に確認を求めます。非対話型シェルではグローバル設定をスキップし、セットアップを完了する方法を案内します。

2. AI クライアントを接続する

Claude Code（~/.claude.json）：

{
  "mcpServers": {
    "hivelore": {
      "command": "hivelore",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/my-project"]
    }
  }
}

Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "hivelore": {
      "command": "hivelore",
      "args": ["mcp", "--stdio", "--root", "/absolute/path/to/my-project"]
    }
  }
}

VS Code：

code --add-mcp '{"name":"hivelore","command":"hivelore","args":["mcp","--stdio","--root","/path/to/project"]}'

3. プロジェクトのコンテキストを準備する

AI クライアントで、bootstrap_project MCP プロンプトを呼び出します。エージェントがコードベースを分析し、.ai/project-context.md を自動的に作成します。

4. Hivelore を通じて作業を開始する

各セッションは 1 回の呼び出しから始まります。

get_briefing(task: "add a Stripe payment integration", files: ["src/payments/PaymentService.ts"])

エージェントは、プロジェクトのコンテキスト、関連モジュールのコンテキスト、順位付けされたコンテキストの手がかりを一度に取得できます。チームがすでに把握していることを再発見するために、grep を繰り返す必要はありません。

ネイティブ MCP に対応していない CLI エージェントは、ラッパーで実行します。

hivelore run -- claude --dangerously-skip-permissions -p "$(cat task.md)"

選択されているモードは、いつでも確認できます。

hivelore agent status
hivelore agent check          # initialize the server and discover its tools
hivelore agent setup          # re-run setup later
hivelore agent setup --yes    # approve user-level MCP config without prompting

セットアップでは、Codex のユーザー設定を含む、古い haive MCP コマンドを移行し、ほかのサーバーと JSONC コメントを保持します。Claude Code、Cursor、VS Code、Windsurf、Codex、および検出された Gemini CLI／Roo Code の設定に対応しています。セットアップ後にクライアントを再起動し、新しいセッションで get_briefing を呼び出してください。サーバーチェックに成功しても、既存のセッションがアクセスできることの証明にはなりません。MCP 接続のトラブルシューティングを参照してください。

5. コミットとプルリクエストをゲートする

hivelore enforce install       # Installs Git hooks + CI enforcement template
hivelore enforce status        # Current enforcement posture
hivelore enforce check --stage pre-commit  # Scan the staged change
hivelore enforce ci            # CI entrypoint (exits 1 on violations)

拒否する内容を決めるのは、enforcement.posture という1つの設定です。

姿勢	拒否する内容
advisory	何も拒否しません。すべて報告されます。作業途中のリポジトリに Hivelore を導入する場合に適しています
balanced（デフォルト）	決定的でコードに紐づく検出結果のみです。ブロックセンサー、アンカー付きアンチパターン、変更したファイルの古いアンカー、成果物の衛生状態が対象です
strict	上記に加え、共有時（pre-push と CI）にプロセスゲート（ブリーフィング、要約、意思決定の網羅性、ブートストラップ）も対象になります

mode、processGate、humanCommits は、姿勢によって設定される個別のスイッチです。特定のスイッチだけ姿勢を上書きするには、そのスイッチを明示的に固定します。hivelore doctor は有効な姿勢とすべての上書きを常に表示するため、ゲートの動作を推測する必要はありません。

姿勢で変更できず、交渉の余地もないルールが1つあります。どの姿勢でも、プロセスゲートがローカルコミットを拒否することはありません。 すべてのコミット前にプロセスゲートでブロックすると、まだ慣れていないリポジトリで --no-verify を使う癖がついてしまいます。コミット時のゲートを通過すると1行が表示され、--verbose を指定するとすべてのチェックが表示されます。古いインストールによって Git フックが壊れたままの場合は、hivelore doctor --fix で再生成できます。

拒否が発生した場合は、該当する行が示されます。

🛡️  A documented lesson refused this commit — about the change you just made:
    • 2026-07-02-attempt-importing-momentjs (src/dates.ts)  use date-fns, not moment
      import moment from 'moment';

1つの教訓を1行で、ファイルと問題のあるソースとともに示します。複合スコアは一切ありません。ゲートは変更を拒否した理由と対処方法を報告し、それ以外の場合は何も表示しません。

---

CLI の概要 — 基本の流れ

hivelore --help には、日常的に使うコマンドだけが表示されます。それ以外のコマンド（レビュー、インポート、診断、ベンチマーク）は、hivelore --advanced --help で確認できます。機能が欠けているのではなく、意図的に対象を絞っています。

すべてのコマンドを網羅したマニュアル： packages/cli/README.md では、各コマンドのフラグと例を説明しています。このページは概念を説明するものであり、マニュアルがリファレンスです。各説明は、どちらか一方にのみ記載されています。

段階	コマンド	動作
セットアップ	hivelore init	.ai/、ブリッジファイル、MCP 設定、フック、CI を作成します
	hivelore doctor	インストールが正常か確認します
	hivelore agent setup	AI クライアント（MCP、フック）を接続します
編集前	hivelore briefing	フィードフォワードコンテキストを提供します。get_briefing の CLI 版です
知識の記録	hivelore memory save	意思決定、規約、注意点を記録します
	hivelore memory tried	失敗したアプローチを記録し、再試行を防ぎます
	(受動的)	フックが検出したセッション中の失敗は、セッション終了時に**proposed の下書きへ自動的に抽出**されます。memory list --status proposed で確認してください。自動で検証されることはなく、センサーが付与されることもありません
検索	hivelore memory search · get	記録を検索してから読み込みます
フィードバック	hivelore sensors check	ドキュメント化された教訓と差分を照合します
ゲート	hivelore enforce finish	タスク完了を宣言する前に終了ゲートを実行します
同期	hivelore sync	古いアンカーを再確認し、ブリッジファイルを更新します
終了	hivelore session end	次のセッションに向けて要約を保存します

CLI と MCP で用語を統一。 メモリ操作の動詞は MCP ツール名に対応しているため、エージェントは一度覚えれば使えます。hivelore memory save/search/get/delete ↔ mem_save/mem_search/mem_get/mem_delete（以前の add/query/show/rm もエイリアスとして引き続き使用できます）。

---

リポジトリで試してみる（5 分、元に戻せます）

おもちゃのようなものではない実際のコードベースで、Hivelore を評価してみませんか？破壊的な変更は行いません。Hivelore が書き込むものはすべて .ai/ といくつかのブリッジファイルの下に置かれ、すべて削除できます。

cd your-project
npm install -g @hivelore/cli
hivelore init -y            # seeds stack packs + git-history scars; writes .ai/ and bridges
hivelore briefing --task "the change you're about to make" --files path/to/file
hivelore doctor             # health + coverage report
hivelore sensors check      # scan your staged diff against documented lessons
hivelore eval --fail-under 50   # retrieval + sensor quality on your own corpus

Hivelore が追加したものをすべて削除するには、rm -rf .ai CLAUDE.md AGENTS.md GEMINI.md .cursorrules .clinerules .continuerules .windsurfrules .rules CONVENTIONS.md .github/copilot-instructions.md を実行し、.github/workflows/hivelore-*.yml ファイルを削除してください。私たちのものではないリポジトリからのフィードバックは、送っていただけるものの中で最も貴重です。うまくいったこと、いかなかったことを添えて、ぜひイシューを作成してください。

Hivelore が適用するチェック

ゲート	チェック内容
最初のエージェントのブートストラップ	コーパスが空の状態では、最初のエージェントにナレッジレイヤーの入力を求めます。入力する内容は、記入済みのプロジェクトコンテキスト、コンポーネントごとのモジュールコンテキスト、主要なコード領域ごとのアンカー付きメモリー、そして主要なコード領域ごとのセンサーです。トリガーはコーパスの状態です。ベースラインが存在すれば、その後のエージェントに対してゲートは何も通知しません。デフォルトでは報告し、posture: "strict" では拒否します
ブリーフィングの読み込み	エージェントが編集前に新しいコンテキストの手がかりを読み込んだかどうかを確認します。デフォルトでは報告します
決定事項のカバレッジ	変更されたファイルが、直近のブリーフィングにある関連するアンカー付き決定事項でカバーされているかどうかを確認します。デフォルトでは報告します
アンチパターンの照合	差分に関連するアンチパターンをゲートで提示します。追加された行で検証済みのブロックセンサーが作動すると、コミットをブロックします。厳格さは enforcement.antiPatternGate（off · review · anchored（デフォルト） · strict）で調整できます
ゲートの保護面の整合性	センサーを弱める差分（block から warn への格下げ、オラクルの変更・削除、抑制範囲の拡大、ブロックセンサーのメモリーの削除）は、レビュー対象として提示されます（sensor-weakened）。ゲートは .ai/ にあるため、弱体化が通知されないまま通過してはなりません
古くなったアンカー	削除または移動されたパスにアンカーされたメモリーはブロックします。ただし、アンカー先が今回の変更で触れたファイルの場合に限ります。それ以外の古いアンカーはコーパスの保守対象として、警告で報告されます
セッションの振り返り	エージェントが終了前に、変更点と残っている作業を記録したかどうかを確認します。デフォルトでは報告します
CI による適用	必須チェックにより、ゲートで失敗がある場合はマージをブロックします

ここでいう「ブロック」の意味。 ゲートが拒否するのは、決定的でコードに結び付いた根拠がある場合に限られます。追加された行で検証済みのセンサーが作動した場合、アンカー付きのアンチパターンがある場合、または変更したファイルに古いアンカーがある場合です。同じ差分なら、どのマシンでも CI でも同じ結果になります。アンカー、リテラルトークン、意味的な一致は、どれほど強いものでもレビュー対象として提示されるだけで、ブロックされることはありません。関連性を示すシグナルは環境によって異なり、同時に現れることは再導入を意味しないためです。 propose_sensor は、記録した教訓をブロックするガードレールに変えるための手段です。

プロセスのゲートは報告します。拒否はしません。 v0.55.0 以降、「ブリーフィングを読み込まなかった」「セッションの振り返りを書かなかった」は要求であり、差分に対する判定ではありません。その理由は実証的なものです。現場からの報告によると、品質ゲートを通過し違反もないテスト済みのコードを含むプッシュが 2 回拒否されました。ペナルティはすべてプロセス上のもので、コードに関するものはありませんでした。開発者が次に学ぶのは --no-verify です。これを使うとセンサーも含めたゲート全体が無効になり、回避されるゲートは何も保護できません。ワークフローも適用したい場合は、enforcement.posture: "strict" を設定してください。

---

コールドスタート — 最初のセッションから価値を提供

hivelore init はリポジトリにすでにあるシグナルをもとに初期データを作成でき、初期データはすべて品質基準を満たすため、コールドスタート時にありきたりで推測可能なアドバイスが出されることはありません。

スタックパックは v0.55.0 以降、オプトイン方式です（--stack auto）。デフォルトで初期データに含めると、新しいコーパスがリポジトリ向けに書かれていないアドバイスで埋まり、実際のセッションの最初のブリーフィングは thin · must_read=0 useful=0 background=3 となっていました。その3件はいずれも、何も教えることなくブリーフィングを占有するスタックパックの月並みなアドバイスでした。空のコーパスのほうが誠実です。補充が必要だとはっきり示せるからです。Git 履歴からの初期データ作成は自動運転モードでも有効です。あなたの履歴にあるリバートは、あなたの傷跡だからです。

ソース	初期データの内容	品質ゲート
スタックパック（--stack auto、オプトイン）	検出されたフレームワークの落とし穴（Next/Nest/Prisma/Flask/Rails/Tailwind/Docker… 20 以上のパック）。シグナルの強いものにはブロックセンサーを設定	具体性の基準 — ありきたりなアドバイスは除外し、CI で監査
Git 履歴（--seed、デフォルトで有効）	リバート／ホットフィックス／回避策のコミットから、記憶のドラフトを作成 — リポジトリに実際に刻まれた傷跡	ノイズ対象の拒否リスト（merge/bump/deps/wip/format を除外）
スキャナーの検出結果（hivelore ingest）	SonarQube / SARIF / ESLint / npm audit の検出結果を、センサー付きの提案済み・根拠付け済み記憶として登録	自動修正可能なスタイル関連ルールを除外（Sonar の数値キーを含む）。保持するには --include-stylistic を指定

hivelore init                                   # Initialize + seed from git history
hivelore init --stack auto                      # ...and add starter packs for the detected stack
hivelore ingest --from sonar issues.json --min-severity major
hivelore ingest --from eslint report.json
hivelore ingest --from sarif report.sarif --dry-run   # Preview without writing

取り込まれた記憶と Git 履歴から作成された記憶は proposed（警告のみのセンサー）として登録されます。hivelore memory list --status proposed で確認し、検証済みのセンサーは hivelore sensors promote で block に昇格してください。

---

.ai/ ディレクトリの構成

your-project/
├── .ai/
│   ├── project-context.md          # Shared project overview
│   ├── modules/                    # Per-component context files
│   │   ├── backend/context.md
│   │   └── frontend/context.md
│   ├── memories/
│   │   ├── personal/               # Private — gitignored
│   │   ├── team/                   # Shared — committed to git
│   │   └── module/<name>/          # Module-scoped memories
│   ├── code-map.json               # Symbol index — deterministic, safe to commit
│   ├── .runtime/                   # Local session state — gitignored
│   └── .cache/                     # Indexes, churn, telemetry — gitignored
├── CLAUDE.md                       # Auto-generated bridge (Claude Code)
├── AGENTS.md / GEMINI.md / …       # …and 10 more native bridges (see below)
└── .github/
    ├── copilot-instructions.md     # Auto-generated bridge for Copilot
    └── workflows/
        ├── hivelore-sync.yml       # Anchor verification on merge
        └── hivelore-enforcement.yml # Required policy gate

ネイティブブリッジ — あらゆるエージェントに対応

MCP を使わない CLI／IDE エージェント向けに、hivelore init は同じコーパスからネイティブ設定ファイルを生成します。これにより、チームの記憶とブロックセンサーを、開発者が使うあらゆるエージェントに渡せます。空のテンプレートだけでなく、強制適用の仕組みも引き継がれます。hivelore sync で最新の状態に保てます。手動で編集しないでください（hivelore bridges sync で再生成してください）。

エージェント	ファイル	エージェント	ファイル
Claude Code	CLAUDE.md	Cline	.clinerules
Cursor	.cursor/rules/haive-memories.mdc	Windsurf	.windsurfrules
Codex / generic	AGENTS.md	Continue	.continuerules
GitHub Copilot	.github/copilot-instructions.md	Cody	.sourcegraph/cody-rules.md
Gemini CLI	GEMINI.md	Zed	.rules
Aider	CONVENTIONS.md	Roo	.roo/rules/haive.md

hivelore bridges list                 # Show target status
hivelore bridges sync --all           # Regenerate every native bridge
hivelore init --bridge-targets cursor,copilot   # Or scope to specific agents

---

コンテキストポリシーの記録

種類	説明
decision	チームが確定したアーキテクチャまたは設計上の選択
gotcha	見落としやすい制約、既知の落とし穴、微妙な不変条件
convention	このコードベース固有の命名、パターン、スタイルのルール
attempt	失敗したアプローチ — エージェントが同じ失敗を繰り返さないための記録
architecture	コンポーネントの境界、インターフェース、データフロー

すべての記録はファイルパスとシンボル名に紐付けられます。紐付け先のコードが変更されると、Hivelore はその記録が古くなっている可能性があると通知します。

---

MCP ツールのリファレンス

ツール	説明
get_briefing	⭐ プロジェクトのコンテキスト、決定事項、注意点、優先順位付きの手がかりを一度の呼び出しで取得します
mem_feedback	適用・却下した結果、または参照した修正済み・検証済みの結果を報告します。必要に応じてセンサーの検知結果を関連付けられます
mem_save	リポジトリのポリシーに関する知識（決定事項、注意点、規約、試行、アーキテクチャ）を保存します
mem_tried	失敗したアプローチを記録し、今後のエージェントが繰り返さないようにします
mem_search	コンテキストレコードを全文検索またはセマンティック検索します
mem_relevant_to	プロジェクトのコンテキストが読み込み済みの場合に、タスクに関連するコンテキストレコードを優先順位付きで取得します
mem_get	簡潔なブリーフィングや検索結果を受けて、コンテキストレコードを1件取得します
mem_update	既存のレコードをその場で修正します。教訓に不足していたアンカーパスを追加できます
propose_sensor	⭐ 記録した教訓を検証済みのガードレールに変換します。パターンを記述すると、Hivelore が現在のコードで誤検知しないことを確認し、ブロックに使えると判断される前に、誤りを検知することを実証します
report_friction	Hivelore 自体に関する問題点をローカルで記録します。情報が送信されることはありません。人間が hivelore report で確認し、課題にするものを判断します
code_map	コードマップがインデックス済みの場合に、手動の grep を使わずにシンボルを検索します
code_search	エクスポートされたシンボルをセマンティック検索します（@hivelore/embeddings と hivelore index code-search が必要です）
mem_verify	アンカーの最新性を確認し、古くなったレコードを検出します
scaffold_test	教訓からインシデント後のテストを保留状態で生成し、それを有効にする sensors propose --kind test の行を作成します（モノレポを認識します）
pre_commit_check	既知の注意点、決定事項、古くなったアンカーに照らして差分を確認します
mem_session_end	次のエージェントに向けて、セッション終了時の要約を保存します

MCP プロファイルを使うと、製品の機能を目的に合わせて絞り込めます。

• HAIVE_TOOL_PROFILE=enforcement（デフォルト）：コンパクトなコーディングエージェント用ハーネスです。
• HAIVE_TOOL_PROFILE=maintenance：コーパスのレビュー、ライフサイクル管理、蒸留、コード検索、プロジェクトコンテキストのメンテナンスに使います。
• HAIVE_TOOL_PROFILE=experimental / full：maintenance の旧エイリアスです（実験的な診断機能は v0.32.0 で削除されました。数か月の利用で、これらすべてを通じた呼び出しは1回のみでした）。

---

MCP プロンプトのリファレンス

プロンプト	説明
post_task	⭐ タスク後のチェックリストです。すべてのセッションを終える前に、学びを記録します
bootstrap_repo	⭐ 最初のエージェント向けのブートストラップです。ブートストラップゲートが要求する知識レイヤー全体（プロジェクトコンテキスト、モジュールコンテキスト、アンカー付きメモ、主要領域ごとの検証済みセンサー）を整備します。現在のコーパスの状態に合わせて具体的なチェックリストを作成し、準備が整うまで bootstrap_project_save → mem_save → propose_sensor を進めます
bootstrap_project	コードベースを分析し、.ai/project-context.md を記述します

---

パッケージ

パッケージ	インストール	説明
@hivelore/cli	npm i -g @hivelore/cli	メイン製品：初期化、強制適用、エージェントの実行、ブリーフィング、メモリー、同期、CI/Git フック
@hivelore/mcp	@hivelore/cli に同梱	ポリシー対応の MCP サーバー
@hivelore/core	依存関係	型、スキーマ、アンカー、ポリシーのプリミティブ、トークン予算
@hivelore/embeddings	npm i -g @hivelore/embeddings	オプション：ローカルのセマンティックランキング（bge-small-en-v1.5、完全オフライン）

このリポジトリに含まれるもの： VS Code 拡張機能（メモリーをインライン表示し、CLI の可観測性を活用した Strategic Cockpit を提供）と、GitHub Action（関連するチームのメモリーを PR コメントとして投稿し、レビュアーやエージェントが見落としがちな制約を確実に把握できるようにします）。

PR のループ。 レビューのフィードバックは、チームの共通認識となる知識です。レビューのスレッドで /hivelore remember <rule> と返信すると、Action が正確な永続化コマンドを返します。または、hivelore ingest --from github-pr <number> を実行すると、PR に対する人間のレビュー指示（「決して〜しない」「常に〜する」「代わりに X を優先する」）が proposed のファイルアンカー付きメモリーに変換されます。それぞれが sensors propose の候補となります。これは、推論ベースのレビューボットには実行できない手順です。 persist-review-learnings が有効な場合（デフォルト）、Action は提案されたメモリーを含む専用ブランチと PR を作成します。リポジトリへの書き込み権限がない場合は、ローカルの ingest コマンドにフォールバックします。トップレベルの PR コメントとレビューのスレッドへの返信は、どちらも同じ経路で処理されます。

構造センサー。 sensors propose --kind ast は、簡潔な --pattern または完全な ast-grep の --rule <json>（inside／has／not／all／any）を受け付けます。JavaScript／TypeScript は組み込みで、Python、Go、Rust、Java は CLI に同梱されたオプションの言語パッケージで利用できます。ルールはブロックに使われる前に、Hivelore の「現状では検出せず、問題がある場合に検出する」検証を必ず通過します。 ネストした関係ルールはデフォルトでは再帰的ではありません。has または inside で子孫をすべて検索する必要がある場合は、"stopBy":"end" を追加します。例：{"has":{"kind":"interpolation","stopBy":"end"}}。

---

適応型ブリーフィング

ブリーフィングに価値があるのは、推測できない知識が含まれている場合だけです。そのため、get_briefing は briefing_value: "high" | "low" を返します。ファイルやタスクに一致するチーム固有の情報がない場合、自動生成されたプロジェクトコンテキストは 1 行のメモに短縮されます（設定：adaptiveBriefing、デフォルトで有効）。これにより、Hivelore はモデルが知らない情報を実際に把握している場合にのみ、より深いコンテキストを提示します。

アンカーは実際の識別力に応じて重み付けされます

アンカーの一致は、具体的であれば最も強力なランキングシグナルです。あらゆるコミットで変更されるファイルでは、ほとんど意味がありません。このリポジトリでの計測では、package.json は 149 件中 106 件のコミットで変更されているため、これにアンカーされたすべての教訓が、すべてのリリースコミットで must_read を宣言していました。コミットの中央値では、8 個の枠に対して 34 個のメモリーが最上位を主張しており、どの 8 個が表示されるかは恣意的でした。

v0.57.0 以降、一致したパスの希少性に応じて一致が重み付けされます。アンカーに適用される単純な IDF です。最近のコミットの 35% を超える割合で変更されるアンカーは、他のすべてより上位になる前に、強いセマンティック一致またはシンボル一致による裏付けが必要です。同じ階層内では具体性で順位が決まります。実際の 25 件のコミットを対象に計測したところ、情報量の少ないアンカーがブリーフィング枠を占める割合は 17% から 4% に減少しました。

変更頻度は、HEAD によって無効化されるキャッシュ済みの git log から取得します。サンプルが少なすぎる場合（浅いクローンや作成間もないリポジトリなど）は unknown と報告され、これまでどおりの順位付けが行われます。「すべてが一般的」とは見なされません。

hivelore doctor は memory-broad-anchors を報告し、ほぼすべての変更を主張するメモリーと、各アンカーが対象とするコミットの割合を示します。解決方法は常に情報の追加です。教訓に、それが実際に対象とする正確なパスを指定してください。

CLI リファレンス

# Setup
hivelore init [--with-ci] [--no-bridges]         # Initialize .ai/ + bridge files + seed from git history
hivelore init --stack auto                       # Opt in to generic starter packs for the detected stack
hivelore init --bridge-targets <all|csv>         # Scope generated bridges to specific agents
hivelore enforce install                         # Install Git hooks + CI enforcement
hivelore enforce status                          # Enforcement posture report
hivelore bridges list/sync [--all]               # Inspect / regenerate native agent bridges
hivelore index code                              # Build .ai/code-map.json
hivelore index code --status [--json]            # Report code-map / code-search index freshness

# Daily use
hivelore briefing [--task <text>] [--files] [--json]   # Print context + relevant memories
hivelore run -- <agent command>                  # Wrap any CLI agent in Hivelore session
hivelore enforce check [--stage pre-commit]      # Policy gate
hivelore enforce ci                              # CI entrypoint
hivelore enforce finish                          # Final agent-exit gate: commit/push, version/tag, CI, npm + GitHub Release
hivelore coverage [--source git|agent|both]      # Find changed files no memory covers
hivelore sync [--since <ref>] [--embed]          # Verify anchors + auto-promote
hivelore sensors list/check/export/promote       # Operate executable memory sensors
hivelore sensors propose <id> --pattern <re>     # Turn a lesson into a VALIDATED guardrail
hivelore report list|submit|dismiss              # Friction agents hit with Hivelore itself

# Memory
hivelore memory save --type <type> --body "<text>" [--paths <csv>]  # Save a memory (anchor to files)
hivelore memory list [--scope] [--status]        # List memories
hivelore memory search <text>                    # Full-text / semantic search
hivelore memory get <id>                         # Read one record
hivelore memory approve [<id>|--all]             # Mark as validated
hivelore memory promote <id>                     # personal → team
hivelore memory tried [--sensor-pattern <re>]    # Record a failed approach (one-shot guardrail)
hivelore memory conflicts [<a> <b>] [--yes]      # List conflict candidates / resolve one pair
hivelore memory verify [--update] [--json]       # Check anchor freshness
hivelore memory import --from <file> [--changelog]  # Import docs or a CHANGELOG as memories
hivelore memory seed [stack|--git]               # Re-seed stack packs / git-history scars

# Cold start (seed from existing signals)
hivelore ingest --from sonar|sarif|eslint|npm-audit <file>  # Scanner findings → anchored memories
hivelore ingest --from <fmt> <file> --dry-run    # Preview without writing

# Indexes (symbol map + semantic search)
hivelore index code [--status]                   # Build .ai/code-map.json / report freshness
hivelore index memories                          # Build the semantic index (first run: ~110MB model)
hivelore index query <text>                      # Semantic search over memories

# Release protocol
hivelore release bump <patch|minor|major>        # Lockstep version bump + CHANGELOG scaffold
hivelore release tag                             # Tag vX.Y.Z at HEAD, push branch + tag
hivelore release ship                            # After the bump commit: pull --rebase → tag+push → poll CI

# Diagnostics
hivelore doctor                                  # Analyze setup, emit recommendations
hivelore eval --fail-under 80                    # Retrieval + sensor quality gate
hivelore eval --semantic-ranking                 # Real embeddings lane (requires index)
hivelore selftest                                # Self-test MCP tools (latency + payloads)

hivelore eval はアンカー付きメモリーから検索ケースを自動生成し、存在する場合は .ai/eval/spec.json も読み込んで、ラベル付きの検索／センサーケースを追加します。このリポジトリでは、このファイルを使って実行可能なメモリーセンサーを CI で維持しており、ガードレールの不具合をリリース前に検出できます。 コミット済みの回帰ベースラインでは、バージョン管理されたチーム／モジュールのメモリーと、決定論的なアンカー／語彙ランキングのみを使用します。ローカルの使用カウンター、個人用メモリー、オプションの埋め込みキャッシュによって、ローカルではベースラインを通過するのにクリーンな CI クローンでは失敗する、といったことはありません。セマンティック検索は、引き続き埋め込み／検索テストスイートと、.ai/eval/semantic-baseline.json を使用する独立した --semantic-ranking CI レーンでテストされます。このレーンでは、パッケージまたはインデックスが利用できない場合、フェイルクローズします。

hivelore doctor は、エージェントがリポジトリの状態を誤って診断する原因となるローカル環境の設定の不整合を報告します。対象には、pnpm の不足、古いワークスペースの dist 成果物、グローバル CLI／MCP のバージョン不整合、古くなったコード検索インデックス、低いメモリーアンカーの網羅率が含まれます。

---

複数コンポーネントのプロジェクト

複数のコンポーネント（フロントエンド／バックエンド／マイクロサービス）を含むプロジェクトでは、コンポーネントごとにモジュールコンテキストを作成します。get_briefing は、編集中のファイルに応じて関連するモジュールコンテキストを自動的に読み込みます。

mkdir -p .ai/modules/backend .ai/modules/frontend

cat > .ai/modules/backend/context.md << 'EOF'
# Module: backend
- Spring Boot, Java 17, PostgreSQL
- Always filter by tenantId in every repository query
- Never modify existing Flyway migrations — create V{N+1}__desc.sql
EOF

cat > .ai/modules/frontend/context.md << 'EOF'
# Module: frontend
- React 19, TypeScript, TanStack Query v5
- All API calls go through hooks in features/<domain>/api/
- Env vars must start with VITE_ to be exposed to the client
EOF

---

開発

git clone https://github.com/Doucs91/hivelore.git
cd Hivelore
pnpm install
pnpm -r build    # Build all packages
pnpm -r test     # Run tests

Node 20 LTS 以上、pnpm 9 以上が必要です。

---

コントリビューション

Issue と PR を歓迎します。大規模な作業を始める前に Issue を作成し、方向性をすり合わせてください。

---

ライセンス

Apache 2.0 — LICENSE を参照してください。