feat: add Grok Build integration

Add native Grok lifecycle capture, provenance, skill installation, and explicit recall guidance while respecting passive hook stdout limits. Release adaptive memory and retention hardening as v0.1.4 with synchronized documentation and metadata.

Author: hungrytech

ARCHITECTURE.md

@@ -4,8 +4,8 @@ WikiBrain is deliberately a bridge, not a fourth knowledge database.
 
 ```text
 Claude Code hooks ─┐
-                   ├─ brainctl ─ SQLite WAL (events and evidence)
-Codex hooks ───────┘       │
+Codex hooks ───────┼─ brainctl ─ SQLite WAL (events and evidence)
+Grok hooks ────────┘       │
                            ├─ owned Markdown vault (durable truth)
                            └─ wikimap CLI (disposable index and recall)
 ```
@@ -26,14 +26,38 @@ Codex hooks ───────┘       │
 
 ## Capture and recall
 
-1. `UserPromptSubmit` redacts and stores a prompt.
+1. `UserPromptSubmit` redacts and stores a prompt from Claude, Codex, or Grok.
 2. `Stop` pairs `last_assistant_message` with that prompt, writes an immutable
    Markdown handoff atomically, then updates Wikimap.
-3. `SessionStart` loads recent handoffs for the same workspace.
-4. `UserPromptSubmit` also searches Wikimap with the current prompt.
+3. On Claude and Codex, `SessionStart` loads recent handoffs for the same workspace.
+4. On Claude and Codex, `UserPromptSubmit` also searches Wikimap with the current
+   prompt.
 5. Claude and Codex encode context with the same
    `hookSpecificOutput.additionalContext` contract.
 
+[Grok Build hooks](https://docs.x.ai/build/features/hooks) provide the five
+events WikiBrain consumes and can discover Claude Code hooks and skills. Grok
+sets `GROK_HOOK_EVENT` and `GROK_SESSION_ID`; WikiBrain uses these variables to
+attribute Claude-compatible hook invocations to provider `grok`. Native Grok
+hooks can instead be installed under `${GROK_HOME:-~/.grok}/hooks/` for a
+Grok-only setup. The two discovery paths should not be enabled together because
+Grok can execute both definitions for one event.
+
+Grok's passive events ignore hook stdout. WikiBrain therefore captures and
+archives Grok events, but deliberately skips hook-time recall and context-usage
+accounting for Grok. This prevents evidence that Grok never received from being
+counted toward adaptive-memory promotion. Grok recall remains explicit through
+the installed skill or `brainctl recall` until the host exposes a supported
+context-injection result.
+
+The observed Grok binary sends lowercase event values such as
+`user_prompt_submit` and `stop`; the adapter maps these to canonical names and
+uses `promptId` as the turn identifier. `UserPromptSubmit` includes `prompt`.
+The observed `Stop` payload includes `transcriptPath` and `reason` but no
+assistant body. WikiBrain records the lifecycle turn with an explicit
+unavailable placeholder and deliberately does not parse the external transcript
+without a separate bounded, redacted transcript contract.
+
 Workspace identity is the nearest Git root inside an allowlisted root. This
 keeps two repositories isolated even when the allowlist is the user's home
 directory. Only a manual `brainctl remember --global` crosses that boundary.
@@ -64,8 +88,8 @@ dirty, recall searches live Markdown instead of trusting stale index results.
 An index generation counter prevents an update that raced with a newer write
 from clearing that dirty state. Source-specific deletion tombstones reject late
 prompt, response, and compaction retries, so an erased page cannot silently
-recreate itself. Session tombstones are keyed by provider plus session ID, so a
-Claude deletion cannot erase an unrelated Codex session with the same ID.
+recreate itself. Session tombstones are keyed by provider plus session ID, so a Claude deletion
+cannot erase an unrelated Codex or Grok session with the same ID.
 
 ## Memory quality
 

CHANGELOG.md

@@ -6,8 +6,19 @@ The project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-07-22
+
 ### Added
 
+- Official Grok Build CLI support with native lifecycle-hook installation,
+  provider/session/workspace provenance, a Grok skill target, and explicit
+  `brainctl recall` and `brainctl remember` workflows.
+- Runtime-verified Grok payload normalization for lowercase event values such as
+  `user_prompt_submit` and `stop`, including `promptId`, `transcriptPath`,
+  timestamp, and termination-reason provenance.
+- English, Korean, Japanese, and Simplified Chinese Grok setup documentation,
+  including the official executable installer, native and Claude-compatible
+  hook paths, duplicate-hook avoidance, and passive-stdout limitations.
 - Adaptive long-term memory promotion for session and handoff evidence actually
   injected across three distinct consumer provider/session pairs, three UTC
   days, and two provider/session/day uses within a rolling 60-day window.
@@ -32,6 +43,11 @@ The project follows [Semantic Versioning](https://semver.org/).
 
 ### Changed
 
+- Grok passive hooks now skip automatic recall computation and injection-usage
+  accounting because Grok ignores passive stdout. This prevents undelivered
+  evidence from contributing to adaptive-memory promotion. Grok `Stop` archives
+  an explicit unavailable-response placeholder rather than reading the external
+  transcript without a bounded redaction contract.
 - Retention now uses conversation capture/completion time rather than Markdown
   registration time and no longer lets stale promotion work protect expired
   turns indefinitely.

README.ja.md

@@ -13,7 +13,7 @@
   <a href="README.zh-CN.md">简体中文</a>
 </p>
 
-WikiBrain は、Claude Code と Codex のための [MIT ライセンス](LICENSE)の共有セカンドブレインです。ライフサイクルフックを通じて機密情報をマスキングした会話の引き継ぎを取得し、永続的なコンテキストを読みやすい Markdown として保存し、ローカルで出典を認識した情報の呼び出しに [Wikimap](https://github.com/dhha22/wikimap) を使用します。
+WikiBrain は、Claude Code、Codex、Grok Build のための [MIT ライセンス](LICENSE)の共有セカンドブレインです。ライフサイクルフックを通じて機密情報をマスキングした会話の引き継ぎを取得し、永続的なコンテキストを読みやすい Markdown として保存し、ローカルで出典を認識した情報の呼び出しに [Wikimap](https://github.com/dhha22/wikimap) を使用します。
 
 ## 目次
 
@@ -33,7 +33,7 @@ WikiBrain は、Claude Code と Codex のための [MIT ライセンス](LICENSE
 
 | ニーズ | WikiBrain が提供するもの |
 | --- | --- |
-| エージェントをまたいで作業を継続 | Claude と Codex が同じプロジェクトスコープのコンテキストを復元できます。 |
+| エージェントをまたいで作業を継続 | Claude、Codex、Grok が同じプロジェクトスコープのコンテキストを復元できます。 |
 | 証拠と記憶を分離 | 90 日の証拠、適応型記憶、明示的な長期記憶を区別して保持します。 |
 | ユーザーの所有権を維持 | Markdown が永続的な正本であり、Wikimap インデックスは破棄して再生成できます。 |
 | 一時的な障害から復旧 | アーカイブ、昇格、リレーション整理の各アウトボックスが中断した処理を再試行します。 |
@@ -64,6 +64,8 @@ brainctl doctor
 | Claude Code の自動記憶 | 新しいセッションで利用可能 | なし。確認には `/hooks` を使用できます。 |
 | Codex の手動記憶 | すぐに利用可能 | `brainctl remember` と `brainctl recall` を使用します。 |
 | Codex の自動取得と呼び出し | 定義はインストールされますが、最初は信頼されていません | 新しいセッションを開始し、`/hooks` を開いて、WikiBrain の 5 つのフックを確認し、現在のハッシュを信頼してください。 |
+| Grok の自動取得 | Grok の Claude フック互換機能で利用可能。ネイティブ設定も対応 | デフォルト設定では追加操作不要。Grok 専用の場合だけ `brainctl setup --clients grok` を使用します。 |
+| Grok の呼び出し | インストール済みスキルと `brainctl recall` が利用可能 | Grok は passive hook の stdout を無視するため、フックによる自動コンテキスト注入には対応しません。 |
 
 ### 3. スモークテストを実行
 
@@ -85,8 +87,8 @@ brainctl forget --document DOCUMENT_ID --apply
 
 ```text
 Claude Code hooks ─┐
-                   ├─ brainctl ─┬─ SQLite WAL: receipts, queues, relations
-Codex hooks ───────┘            ├─ Markdown vault: durable readable truth
+Codex hooks ───────┼─ brainctl ─┬─ SQLite WAL: receipts, queues, relations
+Grok hooks ────────┘            ├─ Markdown vault: durable readable truth
                                 └─ Wikimap: disposable local search index
 ```
 
@@ -96,6 +98,27 @@ Codex hooks ───────┘            ├─ Markdown vault: durable r
 4. `SessionStart` は同じ Git ワークスペースについて、最近のコンテキストとクエリに関連するコンテキストを復元します。
 5. 型付きの `relates-to` および `supersedes` リンクは証拠を接続し、その出所を削除することなく古いガイダンスを抑制します。
 
+[Grok Build 公式フック文書](https://docs.x.ai/build/features/hooks)は
+`SessionStart`、`UserPromptSubmit`、`PostToolUse`、`Stop`、
+`PostCompact` をサポートし、Claude Code のフックとスキルも自動的に読み込みます。
+WikiBrain は Grok のフック環境を検出し、Claude 互換経路のイベントも provider
+`grok` として記録します。ただし Grok は passive hook の stdout を無視します。
+そのため Grok の証拠は自動取得しますが、届いていない呼び出しをコンテキスト注入として
+数えたり、自動呼び出しと主張したりしません。以前のコンテキストが必要なときは、
+Grok に WikiBrain スキルを使わせるか、`brainctl recall` を実行してください。
+実測 runtime payload の event 値は `user_prompt_submit`、`stop` のような
+lowercase で、WikiBrain が内部 lifecycle 名へ正規化します。`UserPromptSubmit` は
+`prompt` と `promptId` を提供します。実測 `Stop` payload には `transcriptPath`、
+`promptId`、`reason` がありますが assistant 本文はありません。そのため WikiBrain
+は利用不可の placeholder を保存し、外部 transcript を自動では読みません。
+
+Grok 専用の設定では、まず [Grok Build overview](https://docs.x.ai/build/overview)
+に従って公式 `grok` 実行ファイルをインストールします。xAI の現在のコマンドは
+`curl -fsSL https://x.ai/cli/install.sh | bash` です。リモート install script は
+実行前に確認してください。その後 `brainctl init --clients grok` を使用します。Grok の Claude
+フックスキャナーを無効にしていない限り、ネイティブ Grok フックと Claude フックを
+同時にインストールしないでください。同じイベントで両方が実行される可能性があります。
+
 各 Git リポジトリは独立した記憶スコープです。プロジェクトの境界を意図的に越えるのは `brainctl remember --global` だけです。フックはフェイルオープンです。不正な形式のイベント、ビジー状態のデータベース、Wikimap 実行ファイルの欠落、タイムアウトがコーディングエージェントを妨げることはありません。
 
 永続化、削除、再試行、信頼境界の詳細は [ARCHITECTURE.md](ARCHITECTURE.md) を参照してください。
@@ -110,29 +133,53 @@ Codex hooks ───────┘            ├─ Markdown vault: durable r
 | 適応型長期記憶 | エージェントのコンテキストへ繰り返し渡された証拠の、長さを制限したマスキング済みスナップショット | 通常の retention 後も保持し、`adaptive` と表示 |
 | 明示的な長期記憶 | 「覚えて」または `brainctl remember` でユーザーが指定した事実や設定 | 通常の retention 後も保持し、`explicit` と表示 |
 
-適応型昇格は直近 60 日のスライディングウィンドウを使います。session または
-handoff が異なる UTC 日付で 3 日以上、異なる consumer provider/session pair で
-3 件以上、実際の最終コンテキストに含まれ、provider/session/day 単位の注入が
-2 回以上である場合に限り対象になります。同じ provider/session pair・同じ日の
-再実行は 1 回として数えます。実際の consumer session identity がない手動
-`brainctl recall` は数えません。最終 `<memory-data>` に届かなかった検索結果は
-数えず、memory ページ
-自身は昇格スコアを増やしません。superseded の証拠は対象外で、workspace 間で
-利用回数を合算することもありません。昇格後に source が superseded された場合、
-派生した adaptive memory も recall から隠します。
-
-これらのハードゲートを満たすだけでは昇格しません。WikiBrain は、説明可能な昇格
-スコアがデフォルトの `0.65` 以上であることも要求します。スコアは session の多様性
-30%、異なる UTC 日にわたる継続性 25%、最終コンテキストへの反復注入 25%、明示的な
-query に基づく consumer session の割合 10%、consumer provider の多様性 10%を
-合算します。反復要素は設定したハード最小値の 2 倍で飽和し、provider の多様性は
-2 provider で飽和します。最終コンテキストに注入されなかった検索結果は寄与しません。
-昇格ページと document metadata にはスコア、しきい値、重み付き要素を記録し、
-`adaptive_memory_min_score` で 0 から 1 のしきい値を調整できます。query-backed として
-数えるのは明示的な検索の direct hit だけで、related と recent fallback は数えません。
-デフォルト値は学習済み確率ではなく、決定的な初期ポリシーです。既存 config にも `0.65`
-が適用されます。以前の hard-gate-only 動作を維持するには、しきい値を `0` にします。
-pending candidate は次回の利用時に再評価されます。
+### 適応型昇格の条件とスコア
+
+自動昇格の対象は `session` と `handoff` の証拠だけです。ユーザーが明示的に
+「覚えて」と指定した内容は、このスコアを経由せず `explicit` 長期記憶になります。
+適応型候補はまず、直近 60 日以内に次のハードゲートをすべて満たす必要があります。
+
+| ハードゲート | デフォルト |
+| --- | ---: |
+| 証拠を受け取った異なる consumer provider/session pair | 3 |
+| 証拠が注入された異なる UTC 日 | 3 |
+| 重複を除いた provider/session/day 単位の注入 | 2 |
+
+ハードゲートを満たすだけでは昇格しません。WikiBrain は次の式を計算します。
+
+```text
+score = 0.30 * min(S / 6, 1)
+      + 0.25 * min(D / 6, 1)
+      + 0.25 * min(I / 4, 1)
+      + 0.10 * (Q / S)
+      + 0.10 * min(P / 2, 1)
+```
+
+| 記号 | 意味 |
+| --- | --- |
+| `S` | 証拠を受け取った異なる consumer provider/session pair 数 |
+| `D` | 証拠が注入された異なる UTC 日数 |
+| `I` | 重複を除いた provider/session/day 単位の注入数 |
+| `Q` | 明示的 query の direct hit により証拠が注入された異なる consumer session 数 |
+| `P` | 異なる consumer provider 数 |
+
+分母の `6`、`6`、`4` は、それぞれデフォルトのハード最小値の 2 倍です。反復に関する
+点数は利用に応じて徐々に増え、その値で飽和します。Provider の多様性は 2 provider
+で飽和します。デフォルトの昇格条件は `score >= 0.65` です。
+`adaptive_memory_min_score` でしきい値を 0 から 1 の範囲で変更でき、`0` にすると
+従来のハードゲートのみの動作になります。
+
+同じ provider/session pair が同じ UTC 日に証拠を再度受け取っても 1 回として数えます。
+実際の consumer session identity がない手動 `brainctl recall` は数えません。最終
+`<memory-data>` に入った証拠だけが点数に寄与し、query-backed の点数は明示的検索の
+direct hit にだけ与えます。Related と recent fallback は含めません。Memory ページは
+自身の昇格点数を増やせず、workspace 間の利用回数も合算しません。Superseded の証拠は
+対象外です。昇格後に source が superseded された場合、派生した adaptive memory も
+recall から隠します。
+
+この式は学習済み確率ではなく、決定的な初期ポリシーです。昇格ページと document
+metadata には合計点、しきい値、重み付き要素を記録します。しきい値未満の候補は
+pending のまま残り、次回の利用時に再評価されます。
 
 昇格では source で確認した証拠を最大 2,000 文字だけ新しい Markdown ページへ
 保存し、source 文書 ID、利用回数、昇格時刻、`memory_kind: adaptive` を記録します。
@@ -254,7 +301,7 @@ AI が提示した計画と権限要求を確認してから進めてくださ
 ```powershell
 $installer = Join-Path $env:TEMP "install-wikibrain.ps1"
 Invoke-WebRequest `
-  "https://raw.githubusercontent.com/hungrytech/wikibrain/v0.1.3/scripts/install-windows.ps1" `
+  "https://raw.githubusercontent.com/hungrytech/wikibrain/v0.1.4/scripts/install-windows.ps1" `
   -OutFile $installer
 Get-Content $installer
 powershell.exe -NoProfile -ExecutionPolicy Bypass `
@@ -291,7 +338,9 @@ brainctl recall "that durable fact"
 | Brain の状態 | `~/.local/share/wikibrain/` | `%LOCALAPPDATA%\WikiBrain\` |
 | Claude フック | `~/.claude/settings.json` | `%USERPROFILE%\.claude\settings.json` |
 | Codex フック | `~/.codex/hooks.json` | `%USERPROFILE%\.codex\hooks.json` |
+| Grok フック（Grok 専用 opt-in） | `${GROK_HOME:-~/.grok}/hooks/wikibrain.json` | `%GROK_HOME%\hooks\wikibrain.json` または `%USERPROFILE%\.grok\hooks\wikibrain.json` |
 | Claude スキル | `~/.claude/skills/wikibrain/` | `%USERPROFILE%\.claude\skills\wikibrain\` |
+| Grok スキル（Grok 専用 opt-in） | `${GROK_HOME:-~/.grok}/skills/wikibrain/` | `%GROK_HOME%\skills\wikibrain\` または `%USERPROFILE%\.grok\skills\wikibrain\` |
 | Codex/Agents スキル | `~/.agents/skills/wikibrain/` | `%USERPROFILE%\.agents\skills\wikibrain\` |
 
 | イベント | WikiBrain の動作 |