🧠 技術調査 - gbrain（AIエージェントの自己配線メモリ層）

本記事は 2026-05-27 時点の公開情報（gbrain v0.41.x 系・master ブランチ）をもとにした技術調査です。

gbrain は、AI エージェント向けの永続メモリ・検索（retrieval）層として設計されたナレッジ合成エンジンです。従来の検索ツールが「生のドキュメント一覧」を返すのに対し、gbrain は「引用付きの合成回答」を生成します。公式の説明は次のとおりです。

"Search gives you raw pages. GBrain gives you the answer."

概要

作者と背景

作者は Y Combinator の President/CEO である Garry Tan です。自身の AI エージェントインフラ（OpenClaw / Hermes）用として開発され、MIT ライセンスで公開されています。

本番実績

検索精度のベンチマーク（240 ページコーパス）では、P@5 49.1% / R@5 97.9% を達成します。グラフ無効時と比較して、P@5 で +31.4 ポイントの改善を示します。

設計思想

gbrain は次の 3 原則に基づいて設計されています。

1. Thin harness, fat skills — コアエンジンを最小限に保ち、能力はバンドルスキルに集約する
2. Markdown as recipes — 設定・拡張はすべて可読な Markdown ファイルで管理する
3. Hardware/database/keys ownership — データはローカルまたは自社インフラ上で完結させる

ナレッジの実体は git リポジトリ上の Markdown ファイルとして管理します（system of record）。バックエンドは Postgres（または PGLite）であり、Postgres はその Markdown を検索用にインデックスする役割を担います。git 上のファイルが常に権威コピーです。

特徴

自己配線ナレッジグラフ

• ページ書き込み時に、LLM 呼び出しなしでエンティティ抽出とリンク生成を実行
• 型付きエッジ（attended / works_at / invested_in / founded / advises など）で関係を表現
• マルチホップトラバーサルにより、ベクトル検索単体では到達できない関係を辿る

ハイブリッド検索（RRF）

• ベクトル検索（HNSW on pgvector）、BM25 キーワード検索、Reciprocal Rank Fusion（RRF）、ソースティアブースト、クエリ意図リライトを組み合わせる
• 3 つの検索モード（conservative / balanced / tokenmax）でコスト・品質のトレードオフを選択
• デフォルトは balanced + ZeroEntropy Reranker

合成回答（synthesis / think）

• gbrain search が生のリトリーバル結果を返すのに対し、gbrain think は引用付きの合成回答を生成
• ギャップ分析により、ブレインが知らない情報を明示
• すべての主張にソースを付与

Minions ジョブキュー

• BullMQ 形状の Postgres ネイティブキュー
• クラッシュリカバリー（二相永続化）、シェルジョブ実行、子ジョブのカスケードタイムアウト、外部 API レートリースをサポート
• S3/Supabase ストレージへのアタッチメントに対応

スキーマパック（schema pack）

• エージェントがページ型構造を進化させる仕組み
• 組み込みパック: gbrain-base（people / companies / concepts / meetings / deal など）と gbrain-recommended（追加ディレクトリ群）
• gbrain schema detect → suggest → review-candidates のフローでカスタムパックを生成
• アクティブパックはすべての読み書きパスに適用

MCP 統合

• stdio および HTTP（OAuth 2.1）の両トランスポートに対応
• Claude Code / Claude Desktop / Cursor / Windsurf / ChatGPT / Perplexity から接続
• クライアントごとの設定が docs/mcp/ ディレクトリに用意

二エンジン構成（PGLite / Postgres）

• PGLiteEngine — WebAssembly 版 Postgres（17.x）。ゼロコンフィグで約 2 秒で起動。個人用途向け（docs/INSTALL.md は約 1,000 Markdown ファイル超で Postgres/Supabase 移行を推奨、README は最大約 50K ページまで対応と記載）。データは ~/.gbrain/brain.db に保存（変更可）
• PostgresEngine — Supabase 互換のフルマネージド Postgres。大規模・チーム・マルチマシン展開に使用
• 両エンジンは BrainEngine インタフェース（約 47 操作）を共通実装

類似ツールとの比較

使いどころは次のように整理できます。

• 人物・組織・取引のように「関係性」を辿りたい知識ベースには、ナレッジグラフを持つ gbrain が向きます
• 単発のドキュメント検索で十分なら、vector-only RAG のほうが構成は軽量です
• ローカル完結を優先するなら PGLite、チーム共有や大規模運用なら Postgres+pgvector を選びます

構造

システムコンテキスト図

コンテナ図

コンテナ：CLI / MCP Server / Operations Layer

コンテナ：BrainEngine

BrainEngine の代表的なメソッド（一部抜粋）は次のとおりです。両エンジンがこの契約を実装するため、CLI / MCP は contract-first で移植可能です。

コンテナ：Retrieval Pipeline

コンテナ：Knowledge Graph

コンテナ：Synthesis Layer

コンテナ：Minions

コンテナ：Schema Pack

コンポーネント図

Retrieval Pipeline のドリルダウンを示します。

コンポーネント：Gather フェーズ

コンポーネント：Merge フェーズ

コンポーネント：Filter フェーズ

reranker は graph augment の後・token-budget enforcement の前に挿入され、その後に deduplication が続きます。

コンポーネント：検索モード

データ

概念モデル

gbrain のデータ構造を所有・利用関係で示します。

情報モデル

主要エンティティの属性を示します。

スキーマパック構造

gbrain は 2 種類の組み込みパックと自作パックをサポートします。

gbrain-base（デフォルト）

ゼロ設定で動作します。Garry Tan 本人のプロダクション Brain トポロジーと一致します。

gbrain-recommended（拡張パック）

gbrain-base に複数ディレクトリを追加します。gbrain schema use gbrain-recommended で有効化します。

各ディレクトリは README.md リゾルバを持ちます。リゾルバは「何が属するか」と「隣接ディレクトリとの曖昧さ解消ルール」を定義します。

構築方法

前提条件

インストール手段 A: agent-driven（推奨）

AI エージェント（Claude Code / Codex / Cursor 等）に以下を貼り付けて委任します。所要時間は約 30 分です。

# エージェントへのプロンプト
Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md

対応プラットフォーム: OpenClaw（Render）、Hermes（Railway）、既存エージェント（Codex / Claude Code / Cursor）。

インストール手段 B: CLI スタンドアロン

# 1. Bun インストール
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"

# 2. gbrain グローバルインストール
bun install -g github:garrytan/gbrain
gbrain --version

# 3. API キー設定
export ZEROENTROPY_API_KEY=ze-...    # 推奨
export OPENAI_API_KEY=sk-...         # フォールバック
export ANTHROPIC_API_KEY=sk-ant-...  # クエリ展開（任意）

# 4. ブレイン初期化（PGLite、約 2 秒）
gbrain init --pglite

# 5. ヘルスチェック
gbrain doctor

# 6. マークダウンの取り込み
gbrain import ~/notes/

# 7. 動作確認
gbrain search "テスト検索"

グローバルインストールが失敗した場合のリカバリ:

git clone https://github.com/garrytan/gbrain.git ~/gbrain
cd ~/gbrain && bun install && bun link

Postgres バックエンドを使う場合は、初期化前に pgvector 拡張を有効化します。

# pgvector 拡張の有効化（DBA 権限で 1 回だけ実行）
psql "$DATABASE_URL" -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Postgres で初期化
gbrain init --url "$DATABASE_URL"

gbrain init オプション

MCP 統合

Claude Code（ローカル、推奨）

claude mcp add gbrain -- gbrain serve

または MCP 設定ファイルに手動追記します（macOS は ~/Library/Application Support/Claude/、Linux は ~/.config/claude/）。

{
  "mcpServers": {
    "gbrain": { "command": "gbrain", "args": ["serve"] }
  }
}

Cursor / Windsurf（stdio MCP クライアント）

MCP 設定ファイルに追加します。

{ "command": "gbrain", "args": ["serve"] }

Claude Desktop / リモートクライアント（HTTP + OAuth 2.1）

gbrain serve --http   # HTTP MCP サーバー起動 + /admin ダッシュボード

ngrok トンネル経由での接続例:

claude mcp add gbrain -t http https://your-brain.ngrok.app/mcp \
  -H "Authorization: Bearer YOUR_GBRAIN_TOKEN"

embedding / reranker プロバイダ設定

複数のレシピが利用可能です。詳細は docs/integrations/ を参照してください。

設定コマンド:

# ZeroEntropy reranker を有効化
export ZEROENTROPY_API_KEY=ze-...
gbrain config set search.reranker.enabled true

# embedding モデルを明示変更
gbrain config set embedding-model "openai:text-embedding-3-small"

# 設定確認
gbrain config get embedding-model
gbrain models doctor

利用方法

必須パラメータ早見表

データ取り込み: gbrain capture

# テキスト直接入力
gbrain capture "覚えておきたい内容"

# ファイルから取り込み
gbrain capture --file ./notes/today.md

# パイプから取り込み
echo "パイプからの入力" | gbrain capture --stdin

# スラッグのみ返す（スクリプト組み込み用）
SLUG=$(gbrain capture "メモ" --quiet)

# Webhook 経由
curl -X POST https://your-brain/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/markdown" \
  -d "# 内容"

検索: gbrain search vs gbrain think

# 生の検索（LLM コストなし）
gbrain search "ポートフォリオ企業の AI 担当者は？"

# 検索スコアの内訳を表示
gbrain search "クエリ" --explain

# LLM 合成・引用付き回答
gbrain think "戦略的な質問"

検索モード（コスト/品質のトレードオフ）:

gbrain config set search.mode conservative   # 低コスト
gbrain config set search.mode balanced       # デフォルト推奨
gbrain config set search.mode tokenmax       # 最大再現率・高コスト

ナレッジグラフ検索: gbrain graph-query

# マルチホップ探索
gbrain graph-query <slug>

# オプション付き例
gbrain graph-query people/<slug> --type attended --depth 2
gbrain graph-query companies/<slug> --type works_at --direction in

エッジはページ書き込み時にゼロ LLM で自動抽出されます。

schema 管理: gbrain schema

gbrain schema active              # 現在のパックとティアを表示
gbrain schema detect              # ファイルシステムからタイプ候補を提案
gbrain schema suggest             # LLM による候補の精製
gbrain schema review-candidates   # 候補を人間がレビュー
gbrain schema review-candidates --apply  # 確認済み候補を適用
gbrain schema use my-pack         # カスタムパックを有効化

設定解決チェーン（7 ティア）

設定は以下の順で解決されます（上位が優先）。

gbrain.yml の設定例:

embedding:
  model: openai:text-embedding-3-small
search:
  mode: balanced
  reranker:
    enabled: true
doctor:
  autoHeal:
    enabled: true
    minInterval: "6h"
    skip: [image_assets, multi_source_drift]

設定操作コマンド:

gbrain config set search.mode balanced
gbrain config get search.mode
gbrain config set search.reranker.enabled true

.gbrain-source ファイルはディレクトリごとのスキーマパック/ソースルーティングを定義します。

運用

sync 運用

通常の同期はリポジトリ更新後に埋め込みを補完する 2 ステップで行います。

gbrain sync --repo /data/brain && gbrain embed --stale

cron 推奨スケジュール（15 分ごと）:

*/15 * * * * gbrain sync --repo /data/brain && gbrain embed --stale
0 2  * * * gbrain dream      # 毎晩メンテナンス
0 3  * * 0 gbrain doctor --json && gbrain embed --stale  # 週次

OpenClaw / Hermes のエージェント cron でも同じコマンドを使います。

federated multi-source sync（v0.41.13.0+）

複数ソースを持つ federated brain では、1 ソースのタイムアウトが全体をブロックしないよう per-source ループ + OS timeout を使います。

# wedged ロックを先に解除
gbrain sync --break-lock --all --max-age 1800

# per-source ループ
for src in $(gbrain sources list --json | jq -r '.[].id'); do
  timeout 600 gbrain sync --source "$src" --timeout 540 || true
done

• --timeout で停止した場合、partial ステータスで終了し last_commit は進みません
• 次回実行時に content_hash の短絡判定で再開地点を自動検出します
• --max-age 1800 は取得タイムスタンプ基準でロックを自己修復します

状態確認・ヘルスチェック

# 総合ヘルスチェック（JSON 出力）
gbrain doctor --json

# ブロッキング・ロックの検出
gbrain doctor --locks

# ページ数・同期ステータス確認
gbrain stats

# 検索ステージごとの集計
gbrain search stats

# 最終 sync タイムスタンプ確認
gbrain config get sync.last_run

# 未埋め込みチャンクを補完
gbrain embed --stale

# CLI アップデート確認
gbrain check-update --json

# JSONB 二重エンコード修復（Postgres 専用、v0.12.2+）
gbrain repair-jsonb --dry-run --json

gbrain models doctor は設定済みモデルに 1 トークンのプローブを送り、サイレント障害を検出します。

doctor auto-heal

doctor:
  autoHeal:
    enabled: true
    minInterval: "6h"
    skip: [image_assets, multi_source_drift]

• enabled: true で診断後に修復コマンドを自動実行します
• minInterval で実行間隔を下限設定し過剰修復を防ぎます
• skip で特定チェックを除外します

dream cycle（cron enrichment）

gbrain dream は全メンテナンスフェーズをブロッキングで 1 回実行します。cron との組み合わせに最適です。

gbrain dream

主要フェーズが順番に実行されます。

dream サイクルが自動処理する enrichment: 重複排除・引用修正・サリエンス採点・矛盾検出。

autopilot デーモン

gbrain autopilot は dream サイクルをインターバルで自動スケジュールする常駐サービスです。

gbrain autopilot

• Postgres 環境では autopilot-cycle ジョブを Minions キューに投入します
• PGLite / --inline では同一プロセス内でサイクルを実行します
• PID ファイルと DB ロックの二重ロックで多重起動を防止します

Minions ジョブキュー（Postgres-native, BullMQ インスパイア）

Postgres ネイティブのジョブキューで、BullMQ の設計思想を踏襲しながらクラッシュ耐性を持ちます。

# ワーカー起動（自動再起動ラッパー）
gbrain jobs supervisor

# ジョブクレームを実行
gbrain jobs work

主要な機能:

• durable subagent: すべての LLM ターンを subagent_messages / subagent_tool_executions に永続化。クラッシュ後も pending ツールのみ再実行して再開
• shell job（v0.14.0+）: 決定論的タスク（API フェッチ・トークンリフレッシュ・スクレイプ）を LLM ゲートウェイからオフロード。有効化に GBRAIN_ALLOW_SHELL_JOBS=1 が必要
• child job cascading timeout: 親ジョブが waiting-children 状態でブロックし、全子ジョブの終了後に集約。timeout_ms で子タイムアウトを設定
• rate leasing: subagent_rate_leases テーブルで Anthropic API の同時呼び出し上限を管理（GBRAIN_ANTHROPIC_MAX_INFLIGHT で変更可）
• S3 / Supabase storage: gbrain files mirror でファイルをストレージバックエンドにアップロード。gbrain files redirect でローカルファイルをメタデータポインタに置換

ジョブ状態ライフサイクル: waiting → active → completed / failed（BullMQ 形状の状態名）。子ジョブ待ちでは waiting-children 状態を取ります。

ベストプラクティス

検索モード選択

3 つのバンドル設定プロファイルから用途に応じて選択します。

デフォルトは balanced + ZeroEntropy reranker です。

reranker 有効化

conservative / balanced では明示的に有効化します。tokenmax では ZEROENTROPY_API_KEY があればデフォルト ON です。

export ZEROENTROPY_API_KEY=<your_key>
gbrain config set search.reranker.enabled true
gbrain models doctor   # プロバイダー疎通確認

• reranker は graph augment（typed-edge traversal）の後・token-budget enforcement の前に挿入されます。その後に deduplication が続きます
• コスト/レイテンシ: 約 $0.025/M tokens、p50 で約 +150ms（docs/architecture/RETRIEVAL.md）
• Floor Ratio Gate（v0.35.6.0+）がメタデータブーストによる弱候補の通過を防止します

source-tier boost とスコアリング

ハイブリッド検索の多層スコアリング構成は次のとおりです。

• Backlink Boost: ページ接続数に比例したスコア乗数
• Salience Boost: 感情強度・出現頻度に基づく重み付け
• Recency Boost: ページ年齢に基づく減衰係数
• RRF（Reciprocal Rank Fusion）: キーワード検索とベクトル検索のランクリストを統合

検索ステージごとのスコア・ブースト・失敗内訳は gbrain search stats で確認します。クエリに --explain フラグを付けると各ステージの内訳を表示します。

skillpack 運用

スキルパックは tool-agnostic なマークダウンファイルとして提供されます。

gbrain skillpack init my-pack
gbrain skillpack doctor my-pack --fix --yes
gbrain skillpack pack my-pack          # 決定論的 tarball + SHA-256
gbrain skillpack search <query>
gbrain skillpack info <name>
gbrain skillpack scaffold <source>

contradiction detection と eval/replay

# 矛盾ペアのサンプリングと LLM 判定
gbrain eval suspected-contradictions

# LongMemEval ベンチマーク（ハイブリッド検索性能）
gbrain eval longmemeval

gbrain eval suspected-contradictions は取得ペアに日付プレフィルタを適用し、クエリ条件付き LLM ジャッジで事実矛盾を検出します。判定結果は永続キャッシュに保存されます。

cron 運用全体像

複数の cron ジョブを quiet hours（オフライン時間帯）とタイムゾーン考慮で組み合わせます。

• 決定論的タスクは Minions shell job でオフロードし、LLM ゲートウェイを節約します
• dream サイクルをオフライン時間に走らせることで、エージェント起動時には最新の知識グラフが利用可能になります
• gbrain jobs supervisor でワーカーの自動再起動を保証します
• brain-first ルール: 外部 API 呼び出し前にまずブレインを検索します

トラブルシューティング

まとめ

gbrain は、git 上の Markdown を system of record としつつ、Postgres にインデックスして「自己配線ナレッジグラフ + ハイブリッド検索（RRF）+ 引用付き合成回答」を提供する AI エージェント向けメモリ層です。PGLite によるゼロコンフィグ起動から Postgres+pgvector の大規模運用まで、同一の BrainEngine インタフェースと MCP 統合で一貫して扱える点が特徴です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント・リポジトリ
  • GBrain GitHub リポジトリ
  • GBrain README
  • GBrain Skillpack ドキュメント
  • GBrain Recommended Schema
  • INSTALL_FOR_AGENTS.md
  • docs/integrations ディレクトリ
  • docs/mcp ディレクトリ
• 解説・リファレンス（deepwiki）
  • GBrain deepwiki
  • Search and Retrieval
  • Database Schema and Migrations
  • Brain and Source Management
  • Getting Started and Installation
  • System and Infrastructure Commands
  • Autopilot, Dream and Maintenance Cycle
  • Durable Agent Runtime
  • Minions Job Queue
  • Git Sync and Multi-Source Brains
  • Configuration and Deployment
• 外部依存・ベンチマーク
  • ZeroEntropy（reranker / embedding プロバイダー）
  • LongMemEval（長期記憶ベンチマーク）