Google Surf Mcp

google-surf-mcp

英語 | 韓国語

スポンサー：SearchApi

ウェブ検索、論文、GitHub リポジトリは、PKM、オントロジー、系譜として保存されます。上のビューは project_memory(action="export", export_format="html", export_view="graph", all_projects=true) を使って生成されています。

「Google 検索、論文、コードベースを、API キーも外部サーバーも不要な、AI エージェント向けの自動ローカルナレッジグラフと系譜に変換します。」

Google Surf は、検索結果と抽出結果をプロジェクト単位のローカルナレッジグラフに保存します。

検索するにつれて、論文、コード、ウェブソース、セッションの意図、計画、実験、決定が個人用 PKM に蓄積されます。新たな調査では、保存済みの知識と最新のウェブ結果を合わせて検索するため、新しい情報を発見し続けながら、作業の繰り返しを減らせます。

プロジェクトはデフォルトで分離されています。一致する DOI、リポジトリ URL、明示的な別名など、検証可能なリンクのみが追加されるため、元の記録を統合することなく、あるプロジェクトの知識を別のプロジェクトで再利用できます。

検索では、完全一致検索、BM25、ベクトル検索、コード検索、グラフ検索、ライブウェブ検索をそれぞれ独立して実行した後、RRF と共通の再ランキングモデルで結果を統合します。

Live web + Papers + Codebases + Project memory
                        ↓
Exact + BM25 + Vector + Code graph + Graph PPR
                        ↓
              RRF + Shared reranker
                        ↓
        Results with evidence and provenance

デフォルトでは、7 つのツールを利用できます：search / search_parallel / extract / scholar_search / project_memory_search / project_memory / health。

リサーチモードと自動キャプチャはデフォルトで有効です。データベースやグラフのサイドカーを起動せずに検索と抽出を利用するには、SURF_RESEARCH=false を設定してください。このモードでは、プロジェクトメモリツールは登録されません。

リサーチモードを無効にしても、ライブの search と search_parallel の結果には、軽量なインメモリ再ランキングが適用されます。ベクトルモデルを読み込んだりローカルストレージを開いたりせずに、プロバイダーの順位とクエリの BM25 順位を RRF で統合します。

ブラウザー検索に API キーは不要です。SearchApi は、オプションのプライマリプロバイダーまたはフォールバックとして設定できます。

主な機能

• Web、論文、コードベースの検索： デフォルトでは Google Web 検索を使用し、論文固有のメタデータには Scholar を使用します。SearchApi は、オプションの主要プロバイダーまたはフォールバックとして機能します。
• Web および学術文書の抽出： HTML および PDF の抽出により、利用可能なタイトル、著者、DOI、出版メタデータ、本文を取得します。search と search_parallel では、要旨または本文全体を含めることができます。
• プロジェクトメモリの自動管理： 検索結果、抽出した本文、コードリポジトリは現在のプロジェクトに保存されます。未読の結果はメタデータのまま保持され、抽出したコンテンツはアクティブな RAG の根拠となります。
• 構造化コードベース検索： Tree-sitter により、ローカルプロジェクトおよび関連する GitHub リポジトリのファイル、シンボル、インポート、呼び出しが関連付けられます。完全一致、BM25、ベクトル、グラフ検索でコードを取得します。
• グラフハイブリッド検索： 最新の Web 検索結果、論文、保存済みコンテンツ、コードベース、プロジェクトグラフを個別に検索します。完全一致、BM25、ベクトル、PPR の候補を RRF と共通のリランカーで統合します。
• オントロジーとデータリネージ： Web ソース、論文、コード、計画、実験、決定を、型付きエンティティと関係として扱います。根拠の経路は、ソースから文書、チャンク、シンボル、根拠、主張へとつながります。
• プロジェクト間のナレッジ再利用： プロジェクトは分離されたままですが、選択したプロジェクトをまとめて検索できます。照合されたエンティティ間は、検証可能なリンクのみで接続されます。
• 永続的な調査履歴： MCP ホストから提供されたセッションの意図、計画、実験、失敗、決定をリビジョンとして保存し、裏付けとなる根拠にリンクします。
• ローカルでのグラフ分析とエクスポート： PageRank、PPR、連結成分、Louvain コミュニティを、別途 Neo4j サーバーを用意せずに実行できます。結果は HTML、Graphviz、D3 JSON、Neo4j インポート形式にエクスポートできます。

検索

• API キー不要のシステム Chrome 検索
• ユーザーの Chrome プロファイルを読み取ったりコピーしたりしない、ログアウト状態専用のプロファイル
• 幾何学的検証を用いた複数戦略の SERP 解析
• スポンサーブロックとナレッジパネルの除去
• CAPTCHA の検出と環境に応じた復旧
• パーサーの自己修復とコンテキストフォールバック

数値

検索速度

	結果
search	4.0-5.1s/クエリ
scholar_search	3.8-5.6s/クエリ

ライブ Web 検索リランカーの検証

保留クエリ 32 件	nDCG@5	MRR	Precision@5
プロバイダー順	0.8949	0.8203	0.6375
BM25 + RRF	0.8971	0.8203	0.6500

• BM25+RRF を使用した Web 検索の応答では、大規模な検索取得ペイロードを最大 75% 削減できます。 1Gb/s 接続のワークステーションで、プロバイダーごとにキャッシュされていないクエリを 3 件ずつ実行して測定しました。ネットワークおよび Google の応答時間は変動します。

技術スタック

• ランタイム： Node.js、TypeScript、Model Context Protocol SDK
• Web 検索： システム Chrome + CDP、Playwright 互換フォールバック、SearchApi フォールバック
• Web 抽出： Mozilla Readability、Turndown
• PDF 抽出： LiteParse/PDFium、オプションの OCR、pdf-lib によるメタデータ解析
• コード収集： ローカルプロジェクトのルートと、アクセス制御された GitHub のスパースダウンロード
• コード解析： ファイル、シンボル、インポート、呼び出し関係に対する Tree-sitter
• コード検索： 完全一致検索、BM25、多言語 E5 ベクトル検索、グラフ PPR
• ローカルデータベース： RocksDB 上の組み込み SurrealDB
• ハイブリッド検索： ライブ Web、論文、プロジェクトメモリ、コードベースの結果を RRF で統合
• ランキング： Reciprocal Rank Fusion と共通のベクトル再ランキング
• グラフ分析： Graphology、PageRank、PPR、連結成分、Louvain コミュニティ
• ナレッジモデル： バージョン管理されたオントロジー、データリネージ、プロジェクト間のスキーマおよびエンティティのリンク
• 復旧： CAPTCHA の復旧、Playwright プールのフォールバック、決定論的なパーサーの自己修復

インストール

Node 20.18.1 以降が必要です。ブラウザモードでは、Google Chrome または Chromium も必要です。

npx google-surf-mcp   # actual MCP - register in client config

最初のツール呼び出し時に、ウォームプロファイルが自動的にブートストラップされます（Chrome が一瞬開く場合があります）。

または、ローカルにクローンします。

git clone https://github.com/HarimxChoi/google-surf-mcp
cd google-surf-mcp
npm install

自動ブートストラップに失敗した場合（まれです）は、手動で実行します。

npm run bootstrap

必要に応じてパスを上書きします。

CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap

Codex 出力の保護（任意）

Google Surf は、モデルに渡される前に大きすぎる Bash 出力をランキングする、オプトイン方式の Codex フックをインストールできます。コマンドは引き続きホストで実行されます。フックが適用するのは、状態を保持しないソース順、完全一致、BM25 による RRF ランキングのみです。Google Surf のデータベースもブラウザも開かず、コマンド出力も保存しません。

npx -y google-surf-mcp@latest hooks install --host codex

Codex を再起動し、/hooks を開いて定義を確認し、信頼してください。シェル出力は 1,500 文字から再ランキングされます。既定の表示予算は 1,500 文字で、クエリに一致する別個のエビデンスレコードまたはブロックがある場合は、最大 3,000 文字まで拡張されます。明示的な上書きでは 3,000 文字を超えることができます。ターンごとの累積出力制限はありません。同一またはほぼ重複する検索を 2 回行うことと、明示的なフォアグラウンドのポーリングループはブロックされます。実行中の統合コマンドに対する既存の write_stdin ポーリングは、このフックではなく Codex ランタイムによって制御されます。

JSON／JSONL の要約では、入力を基準とする JSON ポインター、祖先の識別情報／条件への参照、元の結果値を含むコンパクトなレコードを使用します。Markdown の表の行では、ソース行を含め、ヘッダーと隣接するコンテキストを保持します。選択されたレコードと必須のコンテキストは、まとめて収まる必要があります。収まらない場合、レンダラーはレコードを途中で切り取るのではなく、省略されたことを報告します。プレーンログでは、ブロックの再ランキングを維持します。選択はモデル、データベース、追加のサブプロセスを使わず、決定論的かつ字句的に行われます。コンテキストの抽出には、意味の理解ではなく、構造やフィールド名のヒューリスティックを使用します。選択されなかったフィールドも元の入力には残ります。これらの抜粋は、実験ログや SSOT の履歴に代わるものではありません。入力を基準とするポインターは、永続的な検索ハンドルではありません。インストール済みの既存のフックバンドルで変更後のコードを使用するには、更新が必要です。

npx -y google-surf-mcp@latest hooks status --host codex
npx -y google-surf-mcp@latest hooks update --host codex
npx -y google-surf-mcp@latest hooks uninstall --host codex

Claude Code での使用

これを ~/.claude.json に貼り付けます。

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"]
    }
  }
}

Claude Code を再起動します。project_memory_search と project_memory を含む 7 つすべてのツールを、既定で利用できます。

その他の MCP クライアントでは、設定ファイルに同じ形式の JSON を使用します。

検索プロバイダー

ブラウザー検索が引き続き既定です。SearchApi は、プライマリプロバイダーとして選択することも、ブラウザー検索に失敗した場合のみ使用することもできます。

値	動作
browser	既定です。専用のログアウト済みプロファイルでシステムの Chrome を使用し、標準の検索ウィンドウを非表示にします。SEARCH_API は不要です。複数の MCP セッションで、1 つのローカルブラウザーブローカーを共有します。
searchapi	SearchApi をプライマリプロバイダーとして使用し、このツールのために Chrome を初期化しません。
fallback	現在のブラウザー階層を 1 回試し、ブラウザーエラー、CAPTCHA／レート制限、プロファイルの失敗、またはパーサーの劣化が発生した場合は SearchApi を使用します。人による CAPTCHA の解決は待ちません。ブラウザーから正常な応答が返った場合や、エラーのない空の応答が返った場合は、再試行しません。

SURF_SEARCH_PROVIDER は search と search_parallel を制御します。SURF_SCHOLAR_PROVIDER は scholar_search を制御します。SearchApi モードを使用するには、独自の SearchApi アカウント、キー、利用可能なクレジットが必要です。

SURF_BROWSER_ENGINE=auto は、ローカルデスクトップではネイティブ Chrome を選択し、クラウドまたはリモートデバッグモードでは Playwright 互換パスを選択します。ネイティブモードでは、ヘッドレス Chrome ではなく、通常の非表示 Chrome ウィンドウを使用します。エンジンを固定するには、native または playwright を設定します。

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"],
      "env": {
        "SEARCH_API": "your-searchapi-key",
        "SURF_SEARCH_PROVIDER": "fallback",
        "SURF_SCHOLAR_PROVIDER": "searchapi"
      }
    }
  }
}

ローカルクローンの場合：

{
  "mcpServers": {
    "google-surf": {
      "command": "node",
      "args": ["/abs/path/to/google-surf-mcp/build/index.js"]
    }
  }
}

ツール

• search(query, limit?, extract_mode?, extract_limit?, response_content?, max_chars?) - ライブ検索と読み取りを行うための主要な単一クエリツールです。新しいソースを見つけて読み取る必要がある場合は、PDF をダウンロードしたり、リポジトリをクローンしたり、別途 extract を呼び出したりせず、この呼び出しで extract_mode を設定してください。正確な公開 URL がすでにわかっており、新たに見つける必要がない場合に限り、extract を使用してください。project_id を指定すると、保存済みのプロジェクトナレッジがライブ検索結果と統合されますが、呼び出しがローカル検索のみになることはありません。limit は 1～20 です。抽出の既定値は none です。extract_limit は 1～10 で、既定値は 5 です。1 回の呼び出しの出力を制限するため、response_content の既定値は summary です。
• scholar_search(query, limit?) - Google Scholar のメタデータ検索です。論文は最大 10 件です。ブラウザー、SearchApi のプライマリモード、およびフォールバックモードをサポートしています。
• search_parallel(queries[], limit?, extract_mode?, extract_limit?, response_content?, max_chars?) - 4 タブの連続キューを通じて、ライブ検索と読み取りを幅広く行うための主要な複数クエリツールです。公開ウェブページ、PDF、論文、または GitHub リポジトリを読み取る必要がある場合は、同じ呼び出しで extract_mode を設定してください。ローカルの PDF ツールはローカルファイルまたは視覚的なレイアウト作業に限って使用し、リポジトリのクローンは編集、ビルド、テスト、または Git 履歴全体の確認に限って行ってください。limit はクエリごとに 1～20 です。呼び出し全体に適用される extract_limit は既定値が 12 で、abstract では最大 20、full では既定値かつ上限が 10 です。1 回の呼び出しの出力を制限するため、response_content の既定値は summary です。
• 統合検索の抽出結果には、requested、applied、skipped、truncated、total_chars が報告されます。remaining_urls を extract に渡すと、検索を繰り返さずに抽出できます。
• extract(url, max_chars?, mode?, response_content?) - 新たに検索する必要がない場合に、正確な公開 URL を対象として使う二次抽出ツールです。ソースをまだ見つける必要がある場合は、代わりに extract_mode を指定して search または search_parallel を使用してください。
  • mode="full"（既定値）：調査用の取得として最大 1000000 文字を読み取ります。調査モードでは、決定的な 4000 文字のチャンクを保存します。response_content="full" は最大 50000 文字を返し、summary は 1500 文字のエビデンス抜粋を返します。
  • mode="abstract"：簡易調査（PDF の 1 ページ目または HTML のメタ説明文、約 1500 文字）です。調査モードが有効な場合、ドキュメントのメタデータは簡易調査の内容とともに保存されます。
  • mode="metadata"：本文テキストを含まないメタデータです。利用可能なタイトル、著者、出版物、日付、DOI、説明、キーワード、正規 URL、ページ数などの PDF プロパティを返します。
  • GitHub リポジトリの URL は、メタデータモードでは README を読み取ります。abstract と full は同じダウンロードゲートを使用し、インデックス化するソースの深さのみが異なります。
  • 応答：コンテンツフィールドと利用可能なドキュメントメタデータです。失敗時は例外を発生させず、{ error } を返します。
• project_memory_search(query, query_variants?, project_id?, include_project_ids?, all_projects?, limit?, request_id?, response_deadline_ms?) - 保存済みのローカルナレッジのみを検索します。最大 19 個の任意のバリエーションを、バッチ処理されたクエリ埋め込み、RRF 融合、エビデンスを起点としたグラフ拡張、および query に対する最終リランキングとともに、1 回のブローカーリクエスト内で実行します。応答には最終ランキングからの、クエリに焦点を当てた範囲限定の要約のみが含まれ、保存された本文はデータベース内にとどまります。呼び出し元が指定した request_id により、長時間のクエリを観測可能にし、project_memory を通じて協調的にキャンセルできます。検索候補が得られた後に期限が到来した場合、完了したレーンは破棄されず、明示的に部分結果として返されます。ブラウザーを開いたり、Google や SearchApi を呼び出したりすることはありません。
• project_memory(action, ...) - SURF_RESEARCH=true の場合に、永続的なプロジェクトナレッジを管理します。
  • action="search"：project_memory_search との互換性を保つためのエイリアスです。
  • action="project_update"：既存のプロジェクト名、目的、制約、または保護対象の親項目を、リビジョンを確認しながらプロファイルの改訂として更新します。
  • action="context"：永続的なプロジェクトの目的、確認済みのセッション意図、暫定的な最近のクエリ、現在の計画、科学実験の状態、および観測されたプロセスの稼働状況を分けて表示します。
  • action="get"：型付きまたはレガシー形式のレコードを、範囲が制限された UTF-8 バイト単位で正確に返します。メタデータのみを取得するには body_bytes=0 を設定し、損失のないページ分割には next_body_offset を使用してください。
  • action="show"：件数と有効なレコード ID を含む、範囲が制限された要約を常に返します。detail_level="full" は互換性のために受け付けますが、すべてのレコード本文を出力することはありません。関連する本文には project_memory_search を、1 つの主張またはエンティティには target_id を使用してください。
  • action="record"：送信された本文を保存し、その ID、リビジョン、ステータスのみを返します。受領情報では、元の適用と冪等性を保った再実行を区別します。
  • action="query_status" / action="query_cancel"：実行前に request_id で識別されたローカル検索を確認するか、協調的に停止します。
  • action="export"：スタンドアロンのインタラクティブな HTML エクスプローラー、Graphviz DOT、D3 ノードリンク JSON、または Neo4j インポートバンドルを <research-root>/exports 以下に書き出します。
• health() - ローカルの調査ランタイムを含む、サーバーの状態を返します。 | 必要なこと | ツール | |---|---| | 保存済みの調査とプロジェクトメモリのみを検索する | project_memory_search | | Webで新しい情報を見つける | search | | 新しいWeb検索結果を保存済みのプロジェクト知識と比較する | project_idを指定したsearch | | 複数の新しいWeb検索を実行する | search_parallel |

再生可能な調査コレクション

google-surf-collectは、バージョン管理されたJSON仕様を1つの永続的なMCPセッションで実行します。仕様には、ライブのsearchジョブとローカルのみのproject_memory_searchジョブを混在させることができます。ライブジョブでは同じ呼び出しで本文を抽出できます。一方、ローカルジョブではGoogleを開かずに、インデックス化されたプロジェクト知識を再利用します。

npx google-surf-collect examples/research-collection.example.json

ソースのチェックアウトから実行する場合：

npm run build
npm run research:collect -- examples/research-collection.example.json

プロジェクトのワークフローでは、永続的なセッションと計画の記録、承認済みコードルートの再構築、作成されたローカル知識の検索、グラフのエクスポートも行えます。

npm run research:collect -- examples/project-memory-workflow.example.json

project_memoryコレクションジョブでは、record、rebuild、exportを使用できます。破壊的なforget操作はコレクションスキーマで受け付けられません。全プロジェクトのエクスポートを要求しない限り、プロジェクトレベルのproject_idはすべてのジョブに継承されます。

出力は追記専用のJSONLです。マニフェストには、正規化された仕様のハッシュ、パッケージのバージョン、Gitコミット、Nodeランタイム、プラットフォーム、プロジェクトのセットアップ、サーバーの健全性が記録されます。各検索、記録、再構築、エクスポートの結果には、安定したジョブID、正確なツール引数、試行回数、タイムスタンプ、経過時間、応答、エラー状態が記録されます。成功したジョブは再開時にスキップされ、失敗したジョブは再試行されます。仕様を変更する場合は、新しい出力ファイルが必要です。ランナーに存在しないプロジェクトを作成させる場合は、project_idとともにproject_nameを設定してください。既存のプロジェクトは再利用されます。

ライブ結果のランキングに以前のプロジェクトのRAG状態を影響させない場合は、retrieval_modeをliveに設定してください。結果は引き続きproject_idの下に記録されます。新しいWeb上の証拠と保存済みのプロジェクト知識を組み合わせて意図的にランキングする場合は、hybridを使用してください。APIキーと環境変数の値がコレクションログに書き込まれることはありません。

これにより、コレクションの手順と返されたスナップショットを再生し、監査できます。ただし、ライブのWeb検索結果は、時間、ロケール、ネットワーク経路、上流のランキングによって変わる場合があります。

オントロジーと系譜を用いたグラフハイブリッドRAG

flowchart TB
    subgraph SOURCES["1. Search and research"]
        direction LR
        LIVE["Live web<br/>Google browser • SearchApi fallback"]
        PAPER["Pages and papers<br/>extract • Scholar metadata"]
        PROJECT_INPUT["Code and project records<br/>local roots • GitHub • host-provided session/plan"]
    end

    INGEST["2. Deterministic capture<br/>normalize • deduplicate • content hash<br/>repository source gate • Tree-sitter"]

    subgraph KNOWLEDGE_BASE["3. SurrealDB knowledge base"]
        direction LR
        CONTENT["Content and code index<br/>exact • BM25 • HNSW vector<br/>documents • chunks • symbols"]
        PROV["Data lineage and provenance<br/>source → evidence → assertion<br/>valid time • recorded time • correction"]
        ONTOLOGY["Versioned ontology<br/>core/project term revisions<br/>entity type • relation • alias • merge/split"]
        MEMORY["Project memory<br/>session intent • plan revisions<br/>experiments • decisions"]
    end

    subgraph INTELLIGENCE["4. Graph intelligence"]
        direction LR
        SCHEMA["Cross-project schema linking<br/>type and relation alignment<br/>stable identifier → identity bridge"]
        SIDECAR["Typed graph sidecar<br/>PageRank • Louvain • query-time PPR"]
    end

    FUSION["5. Hybrid retrieval<br/>live • exact • BM25 • vector • graph<br/>deterministic RRF • shared reranker • fresh-web floor"]
    RESULTS["Results + provenance<br/>short storage receipt"]

    LIVE --> INGEST
    PAPER --> INGEST
    PROJECT_INPUT --> INGEST
    INGEST --> CONTENT
    INGEST --> PROV
    INGEST --> ONTOLOGY
    INGEST --> MEMORY
    ONTOLOGY --> SCHEMA
    CONTENT --> SIDECAR
    PROV --> SIDECAR
    MEMORY --> SIDECAR
    SCHEMA --> SIDECAR
    LIVE --> FUSION
    CONTENT --> FUSION
    SIDECAR --> FUSION
    FUSION --> RESULTS
    RESULTS -. "automatic search/extract capture" .-> INGEST

    classDef inputStyle fill:#eef6ff,stroke:#2563eb,color:#172554
    classDef processStyle fill:#fff7ed,stroke:#ea580c,color:#431407
    classDef storageStyle fill:#ecfdf5,stroke:#059669,color:#052e16
    classDef intelligenceStyle fill:#f5f3ff,stroke:#7c3aed,color:#2e1065
    classDef outputStyle fill:#f8fafc,stroke:#475569,color:#0f172a
    class LIVE,PAPER,PROJECT_INPUT inputStyle
    class INGEST processStyle
    class CONTENT,PROV,ONTOLOGY,MEMORY storageStyle
    class SCHEMA,SIDECAR intelligenceStyle
    class FUSION,RESULTS outputStyle

1つのローカルナレッジベース

1つのSurrealDBインスタンスが、次の3つの異なるレイヤーの基盤となります。

• カタログ： 安定したID、リビジョン、プロジェクトの所属、オントロジー、来歴、時間的なリンク。
• ペイロード： 正確な本文、ソースのスナップショット、マニフェスト、アーティファクト参照。同一のコンテンツは1回だけ保存され、IDとバイト範囲を指定して取得できます。
• 派生ビュー： 正確性、BM25、ベクトル、コード、グラフの各インデックスと、コンパクトな現在のプロジェクトビュー。これらはソースハッシュによってバージョン管理され、再構築できます。

単一のローカル調査ブローカーが、埋め込み型のRocksDB接続を管理します。複数のMCPセッションが、認証済みのローカルIPCを介して接続し、範囲を限定した読み取りを並行して実行するとともに、別のデータベースプロセスを開かずに書き込みを直列化します。本文、埋め込み、グラフ構造が重複排除されても、元の証拠と過去の出現箇所は引き続き参照できます。

耐久性のある記録と増分インデックス作成

project_memory は、プロジェクトプロファイル、計画、実験、試行、測定、アーティファクト、ドキュメント、決定、セッションを型付きレコードとして書き込みます。安定したアセット ID にはリビジョンが割り当てられます。同じ冪等性キーを使った不確実な再試行では、コミット済みのリビジョンが idempotent_replay=true および applied_this_request=false とともに返されます。body_path は最大 256 MiB の本文をストリーミングし、アーティファクトマニフェストは分割取得され、スライスされません。get／get_batch は、上限付き本文スパンを通じて、型付きまたはレガシーのレコードを正確に返します。簡潔な書き込みレシートには、受け付けたバイト数、参照、リビジョン、正確な読み戻しハンドルが記載され、送信された本文はエコーされません。

sync は、登録済みのルート、または明示的に指定した変更済みパスと削除済みパスを受け付けます。変更のないルートと親 ID はそのまま維持され、何も変更がない場合は派生インデックスを書き換えません。1 つのファイルが変更された場合は、影響を受ける世代のみを公開します。コード、検索、グラフの公開処理は、1 つの耐久性のあるジョブ ID のもとで実行されます。job_wait はリビジョンカーソルを使用し、job_cancel は安全なステージ境界で停止します。未完了のジョブはプロセスの再起動後に再開されます。ワーカーのソフトメモリ上限に達した場合は、フォアグラウンドリクエストが優先して完了します。再構築可能なインデックスジョブは耐久性のあるステージ境界でチェックポイントを保存し、コミット済みのレコードをキャンセルすることなく、置き換え後のワーカーで再開されます。

オントロジーとプロジェクト横断リンク

バージョン管理されたオントロジーは、エンティティタイプと関係の変更をリビジョンとして保持します。スキーマリンクでは、プロジェクト固有のタイプと関係を共有スキーマに対応付けます。エンティティリンクでは、DOI、リポジトリ URL、明示的なエイリアスなど、検証可能な識別子が一致した場合に限り、同じ論文、リポジトリ、エンティティを接続します。曖昧な候補は自動的にリンクされません。

データと研究のリネージュ

• ソースのリネージュ： source → document → chunk → evidence → assertion
• コードのリネージュ： repository → directory → file → symbol → import/call
• 研究のリネージュ： session → intent → plan revision → experiment → decision

これにより、主張や決定の根拠となるエビデンスを保持しながら、修正済みまたは置き換え済みの履歴も維持します。

グラフ検索

Graphology は SurrealDB から型付きのグラフ投影を構築し、PageRank、連結成分、Louvain コミュニティを計算します。検索時には、関連ノードを起点として PPR ベースのマルチホップ検索を行います。ライブ Web、完全一致、BM25、ベクトル、グラフの候補を、決定論的な RRF と共通のリランカーを使って組み合わせます。

ローカルの複数クエリ検索では、クエリ埋め込みをバッチ処理します。完全一致、BM25、ベクトルの各レーンは RRF まで独立して維持され、グラフ展開、選択チャンクのハイドレーション、再ランキングはそれぞれ 1 回だけ実行されます。グラフのみを使う全プロジェクト検索では、軽量なメモリノードインデックスと検証済みの ID エイリアスを使い、クエリ時にすべてのプロジェクトグラフを構築する代わりに、最大 4 つのグラフスコープを選択します。

クエリ埋め込みに失敗した場合、またはベクトルが返されなかった場合、ローカル検索はリランキング時にモデルを再試行せず、字句検索とグラフ検索の順位を返します。タイミングフィールドは、重複しないウォールクロック時間の区分です。embedding_ms と retrieval_ms の合計は検索の終了時点に達し、rerank_ms は残りのレスポンス処理を対象とします。検索処理は埋め込み処理と重複する場合があるため、retrieval_ms は単独のデータベース実行時間ではありません。指定された response_deadline_ms はブローカーへの受け入れ後に開始します。トランスポートのウォッチドッグには、この期限に加えて、キュー／IPC 用の 5 分間の猶予が維持されます。部分レスポンスの返却後も実行が続くネイティブクエリは、処理が完了するまでブローカーの読み取りスロットを保持します。

リサーチ検索の検証

60 件のクエリを使った回帰フィクスチャで、語彙ベースラインとローカル RAG の全経路を比較します。検索の変更と HNSW の近似検索を切り分けるため、埋め込みスレッドを 1 つに固定し、網羅的なベクトルスコアリングを使用します。以下の表は、別々にプロセスを起動して 3 回実行した結果の中央値です。

60 件の制御済みクエリ	Recall@10	nDCG@10	MRR@10
語彙ベースライン	0.3333	0.3333	0.3333
Exact + BM25 + Vector + Graph RRF	0.9833	0.8194	0.7668
+ 共有リランカー	0.9833	0.8194	0.7668

取得されたすべての対象は、厳密な出所の読み戻し検証に合格しました。このフィクスチャでは、保守的なリランカーによって統合後の順序が維持されました。この検証は、本番環境での検索品質やリランカーによる改善を保証するものではありません。

npm run research:vector-backends -- --rows 5000 は、決定論的なテストベクトルを使って物理表現を比較します。以下のサンプルには E5 モデルの読み込み時間は含まれていないため、対象のマシンで再実行してください。

バックエンド	入力行数	保存されたベクトル数	挿入	クエリ p95	再現率
HNSW	5,000	5,000	1292.1 ms	10.77 ms	1.000
Compact	5,000	1,250	357.1 ms	3.96 ms	1.000
Exhaustive	5,000	5,000	1197.1 ms	289.79 ms	1.000

デフォルトでは、すべてのチャンクを対象としたセマンティック検索を実現するため、引き続き HNSW を使用します。Compact はソースごとに代表的なチャンクを 1 つインデックス化します。この短いレコードのフィクスチャでは、使用メモリが少なく、集計再現率も同等でしたが、長いソースの末尾付近にあるまれな詳細を見落とす可能性があります。

ブローカーと耐久性の検証

最新のローカル 100 クエリ負荷試験	結果
ブラウザブローカーの起動回数	0
アクティブなデータベース所有者の再起動回数	0
クエリ時の RSS 増加量	+10.9 MiB
観測されたリサーチワーカーの最大 RSS	375.5 MiB
アイドル時の排出と透過的な再オープン	合格
変更なしの同期／1 ファイルの増分同期	合格／合格

npm run research:reopen-probe では、バイト単位で正確な本文のページング、225 件の参照を含むページ分割されたアーティファクトマニフェスト、さらにプロセス再起動後に保留中の再構築が再開され、検索可能になることも検証します。負荷試験では、ブローカー、データベース、クエリのライフサイクルにおけるメモリ使用量を切り分けるため、ベクトルモデルを無効にして実行します。ベクトルバックエンドは上記のとおり別途測定しています。

プロジェクトの分離とナレッジの再利用

project_id は、新しい結果の保存先を選択します。include_project_ids は書き込み先を変更せずに、読み取り範囲を拡張します。元のレコードはプロジェクトごとに分離されたままですが、検証済みのスキーマリンクとエンティティリンクにより、論文、コード、実験結果を、選択したプロジェクト間で再利用できます。

インタラクティブなグラフとエクスポート

project_memory(action="export", export_format="html", export_view="graph") を使用します。返されるスタンドアロン HTML はサーバーなしでローカルに開くことができ、連動する 3 つのビューを含みます。1 つのプロジェクトには project_id、選択したプロジェクトを統合したグラフには include_project_ids、すべてのプロジェクトには all_projects=true を使用します。

• PKM は統合されたプロジェクトグラフをコミュニティ別にまとめ、PageRank に応じてノードのサイズを設定します。
• Lineage はソースとコードのリネージをセッション、意図、計画、実験、決定のリネージから分け、両方のフローをステージごとに揃えて表示します。
• Ontology はコアとなる型と関係、揃えられた共有スキーマ、型付きインスタンスを表示します。検証済みの ID レイヤーは、安定した識別子または明示的なエイリアスによってプロジェクト間の一致が証明された場合にのみ表示されます。

データと調査のリネージ

オントロジーと共有スキーマ

検索、型フィルター、1～3 ホップのローカルフォーカス、パン、ズーム、来歴インスペクターはファイル内で使用できます。大規模なグラフでは、ノードの型、PageRank、次数、コミュニティの網羅性のバランスを取った、決定論的なセマンティック投影を使用します。ビューアーはソースと表示中の件数を報告し、内部 ID をローカルエイリアスに置き換え、重複するラベルを区別します。また、ソース ID、ローカルパス、ノード本文、計画テキスト、証拠の引用は埋め込みません。

プロジェクトメニューでは、エクスポートに含まれるすべてのプロジェクトと、統合された All projects ビューを切り替えられます。ローカルデータベース内の名前付きプロジェクトをすべて含めてエクスポートするには all_projects=true を使用し、対象を限定するには project_id と include_project_ids を使用します。キャンバスの空白部分をクリックすると、ローカルノードのフォーカスが解除されます。PNG は現在のキャンバスをエクスポートし、JSON は匿名化されたビューアーペイロードのみを使用して、現在のタブ、プロジェクト、型フィルター、ローカルフォーカスをエクスポートします。スタンドアロンファイルでは nonce で制限されたスクリプト CSP を使用し、ネットワーク接続は行いません。また、ソースリンクは余分な部分を取り除いた公開 HTTP または HTTPS URL のみに許可されます。

Neo4j エクスポート

project_memory(action="export", export_format="neo4j", export_view="graph") を使用します。返されるディレクトリには nodes.csv、relationships.csv、constraints.cypher、load.cypher、manifest.json、README.txt が含まれます。PageRank、コミュニティ、オントロジー、リネージ、プロジェクト ID、ソース ID、証拠 ID は保持されます。ノード本文、計画テキスト、証拠の引用はエクスポートされません。

新規または空のローカルデータベースの場合は、エクスポートディレクトリから Neo4j オフラインインポーターを実行します。

neo4j-admin database import full --nodes=nodes.csv --relationships=relationships.csv neo4j

既存のローカルデータベースの場合は、2 つの CSV ファイルを Neo4j のインポートディレクトリにコピーしてから、次を実行します。

cypher-shell -f constraints.cypher
cypher-shell -f load.cypher

オフラインインポーターは、型付きのノードラベルとリレーションシップ型を作成します。オンラインローダーは SurfNode と SURF_RELATION を使用し、元の種類とリレーションシップ型をプロパティとして保持します。neo4j-admin database import full は新規または空のデータベースを対象としています。既存のデータベースには LOAD CSV を使用してください。公式の Neo4j インポート および LOAD CSV のドキュメントを参照してください。Bolt は接続プロトコルであり、エクスポートファイル形式ではないため、このコマンドは Neo4j サーバーに接続したり、サーバーを変更したりしません。

ストレージの範囲とセキュリティ

リサーチモードはデフォルトで有効です。search、search_parallel、scholar_search、extract の結果は自動的に取得されます。セッションの意図、計画、実験、決定は、MCP ホストが project_memory を通じて送信した場合にのみ保存されます。その後、バージョン管理、オントロジーマッピング、リネージの紐付けが自動的に実行されます。取得モードはサーバーの設定であり、呼び出しごとの引数ではありません。

画像の取得、画像の埋め込み、視覚的な再ランキングは、リサーチメモリの対象外です。OCR は、スキャンされた PDF ページから検索可能なテキストを取得する場合にのみ使用されます。

認証情報と秘密鍵のファイルは、本文のインデックス作成対象から除外されます。HTML エクスポートには、ソース ID、ローカルパス、ノード本文、計画のテキスト、エビデンスの引用は含まれません。ビューアーはネットワークリクエストを開始せず、ユーザーの操作後にのみ、不要な情報を除去した公開 HTTP または HTTPS のソースリンクを開きます。

プロジェクトとアサーションの削除には、件数のプレビューと確認トークンが必要です。削除によって元に戻せるトゥームストーンが作成され、エビデンスと訂正履歴は保持されます。事実の訂正で指定できるのは、target_id、replacement、reason のみです。以前のアサーションは二時点履歴として残ります。計画の改訂は追記のみです。実験はアクティブな改訂に紐付けられ、明示的に success、failed、inconclusive のいずれかで終了する必要があります。ログから結果を推定することはありません。レシートには保存されたカテゴリのみが記載されます。

Project: Graph memory | Session: temporal graph research | Stored: paper 1 (Graphiti), repo 1 (getzep), search summaries 3 | Status: ready

データベースとサイドカーを閉じたままにし、project_memory_search と project_memory を除外するには、SURF_RESEARCH=false を設定します。Obsidian と Notion の同期は含まれておらず、追加される際もプロジェクト単位でオプトインのままとなります。

ローカル操作用 CLI

これらのコマンドは、MCP セッションと同じ認証済みリサーチブローカーを使用します。別の組み込みデータベース所有者やブラウザーを起動することはありません。

npx google-surf-mcp doctor --json
npx google-surf-mcp daemon start --background --no-window
npx google-surf-mcp memory get --project PROJECT --record RECORD --json
npx google-surf-mcp memory sync --project PROJECT --manifest changes.json --json
npx google-surf-mcp memory current --project PROJECT --json
npx google-surf-mcp job wait --project PROJECT --id JOB --after-revision 0 --json
npx google-surf-mcp job cancel --project PROJECT --id JOB --reason "operator request" --json
npx google-surf-mcp daemon drain --json

doctor は受動的に動作します。データベース、ベクトルモデル、グラフを開くことなく、プロセス ID、バージョン、機能、キューのカウンター、メモリのカウンター、キャッシュのバイト数、現在のライフサイクル状態、フォアグラウンド／バックグラウンドの所有状態、チェックポイントの排出状態、およびワーカーの再利用を妨げている具体的な要因を報告します。MCP クライアントが接続したままでも、意味のある処理がアイドル状態になるとブローカーは排出を開始します。アクティブなリクエストとコミットがある場合は排出が延期されます。一方、再構築可能なバックグラウンドジョブは、メモリ圧迫時に安全なステージ境界でチェックポイントを作成します。次のリクエストでは透過的に再接続されます。

環境変数

変数	デフォルト	備考
SEARCH_API	unset	SearchApi API キーです。いずれかのプロバイダー設定が searchapi または fallback の場合にのみ必須です。ベアラートークンとして送信され、リクエスト URL に含まれることはありません。
SEARCHAPI_API_KEY	unset	SEARCH_API の別名です。
SURF_SEARCH_PROVIDER	browser	search と search_parallel のプロバイダーです。browser、searchapi、または fallback を指定します。
SURF_SCHOLAR_PROVIDER	browser	scholar_search のプロバイダーです。browser、searchapi、または fallback を指定します。
SURF_BROWSER_ENGINE	auto	ブラウザーエンジンです。auto、native、または playwright を指定します。ネイティブ Chrome は読み取り専用の CDP アタッチ前にリクエストを実行します。
CHROME_PATH	auto-detected	Chrome バイナリの絶対パス
SURF_PROFILE_ROOT	~/.google-surf-mcp	ウォームプロファイルの保存場所
SURF_RESEARCH	true	ローカルのプロジェクトメモリ、キャプチャ、インデックス作成、project_memory_search、project_memory を有効にします。検索と抽出のみを行う場合は false に設定します
SURF_RETRIEVAL_MODE	hybrid	リサーチ検索ルートです。live または hybrid を指定します。SURF_RESEARCH=true の場合にのみ使用されます
SURF_RESEARCH_ROOT	<profile>/research	組み込み SurrealDB のデータディレクトリ
SURF_RESEARCH_DB_ENDPOINT	unset	任意のリモート SurrealDB エンドポイントです。wss／https が必要ですが、localhost では ws／http も使用できます
SURF_RESEARCH_DB_NAMESPACE	google_surf	リサーチカタログが使用する SurrealDB の名前空間
SURF_RESEARCH_DB_DATABASE	research	リサーチカタログが使用する SurrealDB データベース
SURF_RESEARCH_DB_TOKEN	unset	リモートリサーチデータベース用のベアラートークンです。代わりに SURF_RESEARCH_DB_USERNAME と SURF_RESEARCH_DB_PASSWORD を設定することもできます
SURF_RESEARCH_VECTOR_MODEL	Xenova/multilingual-e5-small	HNSW ベクトル検索と最終リランキングで使用する、384 次元のローカルモデルです。デフォルトのモデルリビジョンは固定されています。ベクトル検索を無効にするには off を指定します。
SURF_RESEARCH_VECTOR_LOW_MEMORY	true	ONNX CPU メモリアリーナとメモリパターンを無効にします。初回インデックス作成を高速化するためにピークメモリの増加を許容する場合は false に設定します
SURF_RESEARCH_VECTOR_THREADS	4	ONNX の演算内スレッド数です。1～16 の範囲に制限されます
SURF_RESEARCH_VECTOR_BATCH_SIZE	8	推論のマイクロバッチサイズです。1～32 の範囲に制限され、生成された埋め込みは各バッチの後にチェックポイントとして保存されます
SURF_RESEARCH_VECTOR_BACKEND	hnsw	ベクトル表現です。hnsw、コンテンツ重複排除を行う compact、または上限付きの exhaustive を指定します
SURF_RESEARCH_REPO_AUTO	true	各検索呼び出しで、関連性の高い小規模な GitHub リポジトリを最大 1 つ、自動でスパースインデックス化します
SURF_RESEARCH_REPO_AUTO_MAX_MB	20	GitHub の自動インデックス作成で検索対象にできるソーステキストの最大サイズです。アセットは除外されます
SURF_RESEARCH_REPO_AUTO_MAX_FILES	2000	GitHub の自動インデックス作成で検索対象にできるソースファイルの最大数です
SURF_RESEARCH_BROKER_IDLE_MS	60000	最後の意味のある処理の後、クライアントが接続されたままでもドレインが始まるまでの待機時間です。アクティブなリクエストとバックグラウンドジョブがある場合、ドレインは延期されます
SURF_RESEARCH_READ_CONCURRENCY	4	ブローカーの読み取りの最大同時実行数です。同一の処理中の読み取りは 1 つの処理を共有します
SURF_RESEARCH_QUERY_TIMEOUT_MS	120000	組み込み SurrealDB クエリごとのタイムアウトです。1～600 秒の範囲に制限されます。タイムアウトした検索レーンは部分的として報告され、他のレーンは引き続き結果を返します
SURF_RESEARCH_GRAPH_CACHE_MAX_MB	64	プロセス内のグラフ投影と分析アーティファクトに割り当てるバイト数の上限です
SURF_RESEARCH_WORKER_SOFT_MEMORY_MB	2048	アクティブな処理の完了後、直ちにアイドル時のドレインを要求する RSS のしきい値です
SURF_RERANK_TRIGGER_CHARS	1500	シェル出力のインターセプトしきい値（この値を含みます）。機密情報を含む出力は、このしきい値を下回っていてもサニタイズされます
SURF_RERANK_MAX_CHARS	adaptive: 1500–3000	シェル要約の文字数上限を任意に指定します。3000 を超える値も指定できます。デフォルトは、出力の繰り返し量ではなく、クエリに一致する個別のレコード／ブロック数を n として、min(3000, ceil(1500 + 750*log2(max(1,n)))) です
GITHUB_TOKEN	unset	リポジトリの調査時に API 制限を引き上げる任意の GitHub トークンです
SURF_RESEARCH_CODE_WORKERS	auto, max 4	初回のコード構造インデックス作成に使用する Tree-sitter ワーカー数です
SURF_LOCALE	en-US	ブラウザーのロケール
SURF_TZ	system tz	例：America/New_York
SURF_HEADLESS	true	Playwright による抽出、互換性処理、復旧パスを制御します。ネイティブ検索では通常のシステム Chrome ウィンドウを非表示にし、CAPTCHA の復旧時のみ表示します。
SURF_REMOTE_DEBUG	false	リモート DevTools を備えたヘッドレスサーバーでは true に設定します。CAPTCHA パスでは DevTools のポートを出力し、ウィンドウを起動せずに例外をスローします。SSH ポートフォワードを使用してローカルマシンから chrome://inspect に接続し、CAPTCHA を解決します。
SURF_CAPTCHA_TIMEOUT_MS	180000	バックグラウンドの人間による復旧ウィンドウの有効期間です。MCP 呼び出しは直ちに返され、このタイムアウトを待ちません。
SURF_IDLE_CLOSE_MS	30000	sequential ctx とプールを閉じるまでのアイドル時間（ミリ秒）です。アイドル時の自動クローズを無効にするには 0 を指定します。値が小さいほどクリーンアップは速くなり、値が大きいほど間隔を空けた呼び出しでもキャッシュが維持されます。
SURF_ALLOW_PRIVATE	false	true に設定すると、extract でプライベートアドレス／ループバックアドレス（localhost、127.0.0.1、10.x、192.168.x、169.254.x など）へのフェッチを許可します。デフォルトでは SSRF 対策としてブロックされます。
SURF_EXTRACT_MAX_CHARS	50000	抽出全体の上限（200～50000）です。要約のデフォルトは 1500 で、呼び出しごとの max_chars は両方の値を上書きします
SURF_EXTRACT_OCR	false	Tesseract でスキャン済み／画像 PDF を OCR します（低速のため、デフォルトでは無効です）
SURF_CLOUD_MODE	false	ヘッドレス／サーバーレスモードです。TLS のバイパス、--no-sandbox、--disable-dev-shm-usage、ワーカープールの無効化、CAPTCHA 時の即時失敗を有効にします
SURF_CASCADE_DISABLED	false	3 段階の自動カスケードではなく、SURF_USE_STEALTH で選択した単一のステルスモードに固定します
SURF_USE_STEALTH	true	初期ステルス段階です。SURF_CASCADE_DISABLED=true の場合にのみ参照されます
SURF_HUMANLIKE_MODE	background	off／background（結果を返した後、結果を待たずに実行）／inline（結果を返す前に完了を待つため、低速）
SURF_RATE_LIMIT_PER_MIN	10	Google 向けリクエストの内部的な 1 分あたりの上限です
SURF_CACHE_TTL_SEARCH_MS	86400000	検索キャッシュの TTL（24 時間）です。キャッシュを無効にするには 0 を指定します
SURF_CACHE_MAX_ENTRIES	1000	キャッシュ名前空間ごとの LRU 上限です
SURF_CACHE_ROOT	<profile>/cache	キャッシュディレクトリ
SURF_INSECURE_TLS	=SURF_CLOUD_MODE	--ignore-certificate-errors（クラウドモードでは自動的に有効になります）
SURF_NO_SANDBOX	=SURF_CLOUD_MODE	--no-sandbox（クラウドモードでは自動的に有効になります）
SURF_TELEMETRY	false	{SURF_TELEMETRY_ROOT} に JSONL イベントログ（検索結果、キャッシュヒット／ミス、ツールエラー、パーサーの古さ）を記録するには true に設定します。自己修復パイプラインへの入力として設計されています。デフォルトでは無効です。
SURF_TELEMETRY_ROOT	<profile>/telemetry	JSONL テレメトリファイルのディレクトリです。UTC の日付ごとに 1 ファイル（YYYY-MM-DD.jsonl）が作成されます。
SURF_SELF_HEALING	true	戦略ごとの結果追跡と並べ替え結果の永続化を行います。並べ替えが始まるには、修復側が結果で 3 回勝つ必要があるため、単一の呼び出しによる頻繁な切り替わりは起きません。デフォルトの戦略順を固定するには false に設定します。
SURF_SELF_HEALING_FILE	<profile>/.heal/strategy-order.json	修復状態の保存先です。一時ファイルへの書き込み後に名前を変更するアトミック書き込みを行い、5 秒間隔でまとめて書き込みます。
SURF_LLM_HEAL	false	ワークフロー専用の repairWithLLM ヘルパーで、LLM を使ったセレクター修復をオプトインで有効にします。デフォルトでは無効で、サードパーティーへの LLM リクエストは送信されません。
SURF_LLM_PROVIDER	anthropic	LLM 修復プロバイダーです。anthropic または orcarouter を指定します。
SURF_LLM_MODEL	provider default	LLM を使った修復に使用するモデルです。Anthropic のデフォルトは claude-sonnet-4-6、OrcaRouter のデフォルトは orcarouter/auto です。
ANTHROPIC_API_KEY	unset	Anthropic プロバイダーで LLM 修復が有効な場合にのみ使用する Anthropic キーです。
ORCAROUTER_API_KEY	unset	OrcaRouter プロバイダーで LLM 修復が有効な場合にのみ使用する OrcaRouter キーです。
ORCA_KEY	unset	ORCAROUTER_API_KEY の別名です。

埋め込みストレージのリソース上限

埋め込みストレージでは、マシンのスペックに応じて設定されるサーバーのデフォルト値の代わりに、RocksDB ブロックキャッシュ 512 MiB、HNSW ベクトルキャッシュ 128 MiB、書き込みバッファー 32 MiB を 2 つ、バックグラウンドジョブ 2 つがデフォルトで設定されます。明示的に設定した SURREAL_HNSW_CACHE_SIZE、SURREAL_ROCKSDB_BLOCK_CACHE_SIZE、SURREAL_ROCKSDB_WRITE_BUFFER_SIZE、SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER、SURREAL_ROCKSDB_THREAD_COUNT、SURREAL_ROCKSDB_JOBS_COUNT が優先されます。

バックグラウンドでのインデックス作成は、一度に 1 つのジョブを実行します。同じプロジェクト内でキューに入ったキャプチャは、現在のインデックス作成パスを共有し、保留中のキャプチャリクエストはブローカーの再起動後も保持されます。推論呼び出しは 1 つのキューを共有し、小さな埋め込みバッチはそれぞれ、キューが空かどうかを確認する前に保存されます。ドキュメントのインデックス作成では、無関係なコード本文を読み込みません。既存のキャッシュ済み埋め込みは引き続き再利用でき、バッチ設定を小さくしても全件のインデックスを再作成する必要はありません。これらはコンポーネントごとのリソース上限であり、プロセス全体の RSS に対する厳密な上限ではありません。ネイティブストレージのデフォルト設定は、ブローカーがデータベースを開く際に適用され、すでに実行中のブローカーには適用されません。

OrcaRouter

SURF_LLM_HEAL=true
SURF_LLM_PROVIDER=orcarouter
ORCAROUTER_API_KEY=...
SURF_LLM_MODEL=orcarouter/auto

トラブルシューティング

• ネイティブ検索では、CAPTCHA が表示されると現在のセッションを開いたままにして、Chrome を表示します。そのウィンドウで CAPTCHA を解決して再試行してください。次の呼び出しでページが検証され、非表示ウィンドウガードが復元されて、同じセッションが続行されます。SearchApi フォールバックは SURF_SEARCH_PROVIDER=fallback および SURF_SCHOLAR_PROVIDER=fallback で引き続き利用できます。
• Playwright の CAPTCHA 復旧には 4 つのモードがあり、環境変数に応じて自動的に選択されます。
  • デフォルト（ローカルデスクトップ）：OS 通知が表示され、ヘッド付き Chrome が開いて、呼び出しが返ります。CAPTCHA を解決して再試行してください
  • SURF_HEADLESS=false：通知なしでヘッド付き Chrome が開きます。CAPTCHA を解決して再試行してください
  • SURF_REMOTE_DEBUG=true：DevTools のポートと手順が表示されます。ローカルで chrome://inspect に接続して解決してください
  • SURF_CLOUD_MODE=true：CAPTCHA_REQUIRED エラーで即座に失敗します
• ヘッド付き Chrome が CAPTCHA ではなく、通常の検索ボックスを開く場合：検索ボックスに任意のクエリを入力して Enter キーを押してください。以降の呼び出しは正常に動作します。
• 「Chrome not found」：Chrome をインストールするか、CHROME_PATH を設定してください。
• 古くなったセレクター：実行時にストラテジーの順序を変更して対応します（SURF_SELF_HEALING、決定論的）。手動で修復ワークフローを実行する方法もあります（SURF_LLM_HEAL、任意、人によるレビューが必要で、自動マージは行われません）。
• Playwright の検索が想定より遅い場合：health().pool.fallback を確認してください。true は、ワーカープールが単一のコンテキストを使用していることを示します。ネイティブ検索では、MCP セッション間で認証済みのローカルブラウザブローカーを 1 つ使用します。ブローカーは非表示の Chrome プロセスを 1 つ保持し、search、search_parallel、scholar_search 用に最大 4 つのタブを再利用します。クエリの開始タイミングはずらしてあります。CAPTCHA が表示されると、そのセッションは保持されたままになり、ユーザーが解決できる状態になります。次の呼び出しでウィンドウガードが復元されます。ブラウザーがクラッシュした場合は、次の呼び出しで新しいセッションが開始されます。
• SSRF：extract はデフォルトで localhost、プライベート IP、AWS メタデータをブロックします。許可するには SURF_ALLOW_PRIVATE=true を設定してください。
• キャッシュのクリーンアップ：npm run cache:clear は検索／抽出キャッシュとダウンロード済みのベクトルモデルキャッシュを削除します。リサーチ DB は削除しません。
• ローカルのリサーチ DB はアプリケーションによって暗号化されません。マシンやバックアップに保存されたデータを保護する必要がある場合は、BitLocker や FileVault などのディスク暗号化を使用し、OS アカウントのアクセス許可を設定してください。

変更履歴

CHANGELOG.md を参照してください。

ライセンス

MIT