magpie-search

Magpie Search

フェデレーテッド検索エンジン — AI エージェントや LLM が、推論の根拠となる真実を見つける必要があるときに手を伸ばす検索エンジンです。

---

コンピューターがいきなり再起動した、あるいはセッションの途中で停電に見舞われた経験はありませんか？ エージェントが保持していたスレッドはすべて失われてしまいます。もう、その取り戻すためのツールがあります。エージェントが失ったものを二度と忘れないように。 Magpie は、あなたの AI がこれまでに扱ってきたすべてをローカルでインデックス化するので、クラッシュは記憶喪失ではなく一時的なつまずきで済みます。

Magpie とは

通常の検索エンジンは 1 か所だけを調べます。Magpie は 1 つの問いを受け取り、重要なすべての場所へ同時に展開します — AI の会話履歴全体、マシン上のファイル、構造化されたナレッジグラフ、ベクトルストア、そしてライブのウェブ — そして、答えが実際に存在する場所からそれを引き戻します。5 つのソース、1 回の呼び出し。

さらに、それぞれを適切な方法で検索します。正確なトークン — ファイルパス、エラー、コードの 1 行 — がわかっているときは、完全一致の文字列や正規表現で grep できます。キーワードで検索できます。意味で検索できるので、言葉が一致しなくても目的のものを見つけられます。これらすべてを一度に実行できます。

そして、それを信頼できるものにする部分を行います。すべてを 1 つのランク付けされた回答に統合し、各結果には信頼ティア — fact > reference > lead > stale — が付きます。確かなソースは上位に上がり、曖昧なものは検証すべきリードとしてマークされ、重複は統合され、すべてが AI のコンテキストを溢れさせないように調整されます。深く掘り下げるよう頼めば、1 つの問いを多数に展開し、ページを読み、何個の独立したソースが一致しているかを教えてくれます — エージェントの大群なしで、完全なリサーチスイープを行えます。

これは完全にマシン上で動作します。サーバーもアカウントも不要で、テレメトリーもオンにしない限りありません。AI のトランスクリプトとファイルは一切外部に出ません。MCP を介して動作するどの AI にも接続できるので、エージェントは必要になった瞬間に 6 つのソースすべてにアクセスできます。

これは AI — エージェントまたは LLM — のためのツールです。

収録内容

その中核にあるのは、AI のトランスクリプトのローカルインデックスです。SQLite データベースに、次の 2 つの構造が並行して構築されています —

• FTS5 全文インデックス(BM25 キーワードランキング)、および
• 小さな all-MiniLM-L6-v2 モデルによってローカルで生成された 384 次元埋め込みのベクトルインデックス(sqlite-vec)。

すべては取り込み時に秘匿化されます — スクラバーが約 30 種類の秘密情報(キー、トークン、秘密鍵、接続文字列)を、1 バイトたりともインデックスに到達する前に除去します。

そのインデックスの上に、5 つの検索モードが載っています:

モード	動作
grep	リテラル / 正規表現マッチ(完全一致トークン: パス、エラー、コード)
lexical	FTS5 / BM25 キーワード
semantic	埋め込み K-NN、ベクトルインデックスにおけるコサイン距離
hybrid	lexical + semantic を RRF で融合
rerank	hybrid の後、クロスエンコーダー(jina-reranker)が各候補を再スコアリング

その周囲にフェデレーション層があり、これが本ツールをフェデレーテッドにしています:

• プロバイダープラグインシステム。 5 つのバックエンド(トランスクリプト、ファイル、ナレッジグラフ、ベクトル、Web)があり、それぞれが信頼ティアでタグ付けされた Hit オブジェクトを返します。
• ファンアウト: 1 つのクエリがすべてのプロバイダーへ同時に送信され(ワーカー数 ≤8)、それぞれに 5 秒のタイムアウトがあり、フェイルオープンします — 遅いソースは呼び出しをブロックするのではなく、何も寄与しません。
• 信頼重み付き RRF 融合 — Reciprocal Rank Fusion で、各ソースの順位にその信頼重み(fact ×3、reference ×2、lead ×1、stale ×0.3)を乗算し、減衰定数は 60 です。これが 6 つの異種ソースを 1 つの誠実なランキングに統合する計算です。
• コンテンツハッシュによるソース横断の重複排除 — 3 か所で見つかった同じ事実は 1 つのヒットに集約され、他にどこで出現したか(裏付け)がタグ付けされます。
• トークン予算トリムにより、統合された集合が呼び出し元 AI のコンテキストをオーバーフローしません。

そしてこれらすべてを MCP サーバーを通じて AI に公開します — エージェントに渡すツールはまさに次のとおりです: search、recent、session、list_sessions、stats、reindex。このリストにないものに注目してください: 回答を書き込むものは何もありません。

なぜこれは RAG ではないのか

RAG = Retrieval-Augmented Generation です。これは 2 段階のパイプラインであり、決定的な段階は 2 番目です: レトリーバーがチャンクを見つける → それらがプロンプトに詰め込まれる → 言語モデルが文章の回答を生成する、という流れです。「G」はこの名前の要点そのものであり、回答を書くジェネレーターがなければ、それは RAG ではありません。

Magpie には G がありません:

1. 検索経路のどこにもジェネレーターが存在しません。 Magpie 内の何も自然言語の回答を組み立てません。モデルに最も近いもの — クロスエンコーダーリランカー — は、結果ごとに関連性の数値を出力し、リストを並べ替えます。それはスコアを付けるだけで、決して文を書きません。
2. 「ランク付けされたヒットはこちらです」で止まります。 RAG はプロンプトの組み立てとモデル呼び出しを所有します。Magpie は融合され信頼でランク付けされた結果を返し、MCP を通じてそれらを引き渡します。AI が次に何をするか — そもそも何かを生成するかどうか — は AI の仕事であり、Magpie の外側です。
3. そのレトリーバーは RAG のレトリーバーより劣るどころか、はるかに優れています。 教科書的な RAG のレトリーバーは 1 つのベクトルストアです: クエリを埋め込み、コサインで top-k、以上。Magpie の検索は 6 つのソース、5 つのモード、信頼重み付き融合、ソース横断の重複排除です。それははるかに高性能な「R」です — しかし、それでも依然として R にすぎません。

Magpie を AI に接続すれば、そのペアは RAG を形成できます — Magpie が R、あなたが持ち込む AI が G です。しかし Magpie 単体が出荷するのは R のみであり、しかも通常より強力な R です。それは真実を見つけてランク付けしますが、決して回答を生成しません。

ディープウェブ検索 — トークンコストを抑えつつ研究の幅を確保する

「ディープリサーチ」でコストがかかるのは 推論 の部分であり、マルチエージェント アプローチではそのコストを N 倍支払うことになります。エージェントごとに 1 つの完全な LLM コンテキストが必要で、1 つの質問に対してしばしば 数百万 トークンに達します。しかし、推論を分散させる必要はありません。すでにコンテキスト内にある 1 つの高性能モデルが統合できます。必要なのは 検索 の幅だけであり、ウェブ検索は純粋な retrieval で、LLM トークンはゼロ です。

magpie-search deepweb はこの非対称性を基盤としています。複数のサブクエリをウェブに対して並列に発行し、信頼度加重 RRF + URL 単位の重複排除によって 1 つのコンパクトでトークン予算に合わせて調整されたソースセットに統合し、オプションで上位ページの本文を読み込み（これもトークン消費なし）、さらに結果を裏付ける独立ドメインの数を報告します。これは、リサーチスウォームがエージェントに報酬を支払って行わせる検証を、エージェントなしで実現したバージョンです。

つまり、マルチエージェントのディープ検索の幅、ページ読み込み、裏付けが得られますが、モデルが支払うのは、調整済みの結果セットに対する 単一の統合パス のみです。

トークンコストの実測 — 1 つのディープな質問:

アプローチ	モデルが支払うトークン
マルチエージェントのディープリサーチスウォーム（N 個のエージェントがそれぞれ自分のコンテキストにページを読み込む）	約 2,000,000
magpie-search deepweb --thorough（6 アングル → 12 ソース、12 ページの全文を読み込み）	約 1,050

これは 約 2,000 倍少ないトークン — コストは約 1/2000 — です。検索とページ読み込みが純粋な retrieval（モデルトークンはゼロ）であり、モデルは調整済みで裏付けが取れたセットに対して最後の統合パスだけを行うからです。

# one question, several angles, read the top pages — all token-free retrieval
magpie-search deepweb "the question" --q "another angle" --q "a third angle" --thorough

ループ内のモデルは、統合され裏付けが取れたセットに対して 1 回の統合パスを行います。節約の仕組みはこれだけです。幅は無料で、支払うのは答えの分だけです。

---

インストール

pip install magpie-search

ライブウェブ検索と deepweb には web エクストラが必要です:

pip install "magpie-search[web]"

これがない場合、--sources web と deepweb は 結果を返しません — web プロバイダーはフェデレーテッド検索を決して壊さないように、fail soft する設計になっているため、依存関係の欠如は結果が見つからなかった検索とまったく同じに見えます。1.3.1 以降では、黙って失敗する代わりに stderr に 1 行の理由も出力します。

または、最新版をソースから直接インストールします:

pip install "git+https://github.com/xfloukiex-lab/magpie-search.git#egg=magpie-search[web]"

オプション — ローカル LLM 機能を追加します（クロスエンコーダーリランカーはベースインストールで動作します。セッションサマライザーには Ollama が必要です）:

# 1. Install Ollama (free, runs entirely locally) — https://ollama.com/download
# 2. Pull the model magpie-search uses
ollama pull phi3.5

Windows、macOS、Linux 上の Python 3.10 以降。

クイックスタート

magpie-search index                               # build the index (incremental)
magpie-search search "that retry backoff thing"   # keyword search
magpie-search search --mode hybrid "..."          # keyword + semantic, fused
magpie-search search --mode rerank "..."          # + cross-encoder rerank
magpie-search stats                               # sanity-check the index

AI に接続する (MCP)

Magpie は Model Context Protocol を話すため、MCP 対応のあらゆるエージェントから呼び出せます。クライアントをバンドルされたサーバーに向けます:

// e.g. an MCP client config
{
  "mcpServers": {
    "magpie": { "command": "magpie-search-mcp" }
  }
}

これでエージェントは search、recent、session、list_sessions、stats、reindex を利用できます — フェデレーテッド、信頼度ランク付き、コンテキスト予算対応です。

CLI リファレンス

コマンド	内容
magpie-search index	~/.claude/projects/ に対する増分インデックス処理
magpie-search search "q"	検索 — --mode grep|lexical|semantic|hybrid|rerank
magpie-search recent --n 30	最新セッションの最新 30 メッセージ
magpie-search session SESSION-ID	1 つのセッションの完全なトランスクリプト
magpie-search list	最近のセッション
magpie-search stats	インデックスサイズ、最終インデックス時刻、行数
magpie-search backup	~/.claude/projects/ を設定可能な保存先にバックアップ

すべてのコマンドに --help を付けると、完全なオプションを確認できます。

Python API

import magpie_search

results = magpie_search.search("retry backoff", mode="hybrid", k=5)
for h in results["hits"]:
    print(h["trust"], h["source"], h["snippet"])

# LLM features (needs Ollama + phi3.5)
import magpie_search.llm
ranked  = magpie_search.llm.search_rerank(query="retry backoff", k=3, pool=10)
summary = magpie_search.llm.summarize(session_id="abc-123", n_messages=80)

バックアップ

magpie-search backup はトランスクリプトツリーを任意の保存先にコピーします — ローカルフォルダ（デフォルト、設定不要）、リモート SSH ターゲット（NAS / ホームサーバー）、または VM の起動/サスペンドを伴うリモート SSH ターゲットです。~/.magpie-search/backup.env で設定します:

[email protected]
MAGPIE_SEARCH_BACKUP_SSH_DEST=~/claude-transcripts/

便利なフラグ: --dry-run、--no-suspend、--show-config。バックアップはコピーであり、元のデータを削除することはありません。

設定

すべてが環境変数で制御され、適切なデフォルト値が用意されています。

変数	デフォルト	内容
MAGPIE_SEARCH_HOME	~/.magpie-search	データディレクトリ (DB、モデル、ログ)
MAGPIE_SEARCH_MODELS_DIR	$MAGPIE_SEARCH_HOME/models	fastembed モデルキャッシュ
MAGPIE_SEARCH_OLLAMA_HOST	http://localhost:11434	Ollama サーバーの URL
MAGPIE_SEARCH_TOKENIZER	heuristic	正確な予算カウントには tiktoken を設定します
MAGPIE_SEARCH_AUDIT_LOG	$MAGPIE_SEARCH_HOME/llm-audit.jsonl	呼び出しごとの監査ログ

サマライザーは 6 つのプローブからなるガードレールスタック (長さ、 固有名詞の安全性、識別子の安全性、拒否のドリフト、意味的グラウンディング、 自己検証) を通過します。trust: clean となるには 6 つすべてが合格する必要があります。いずれかが失敗するとサマリーは抑制され、trust: degraded が返されます — 誤りより静けさを優先します。生のメッセージは magpie-search session SESSION-ID で引き続きアクセスできます。

プライバシー

Magpie Search はローカルツールです。サーバーなし、アカウントなし、自動更新なし、クラッシュレポーターなし、そして明示的にオプトインしない限りテレメトリーはありません (以下を参照)。あなたのトランスクリプト、インデックス、監査ログ、モデルキャッシュ、バックアップはすべてあなたのマシン上に存在します。

オプトインのテレメトリー。 テレメトリーはデフォルトでオフです — magpie-search telemetry enable を実行する (または MAGPIE_SEARCH_TELEMETRY=1 を設定する) まで magpie は何も送信しません。オンの場合、送信されるのは匿名の使用状況のみです: 実行されたコマンド、検索モード、結果/ヒット数、レイテンシ、エラークラス、および magpie/python/OS のバージョンで、ランダムなインストール ID でタグ付けされます。あなたのクエリ、ファイルパス、結果、トランスクリプトの内容、ユーザー名、IP は決して送信されません — telemetry.py のハードなコンテンツファイアウォールが、数値または短い列挙トークン以外のすべてを遮断します。いつでも magpie-search telemetry disable で無効化でき、magpie-search telemetry status で状態を確認できます。これが行うネットワーク呼び出しは次のものだけです: ローカルの Ollama サーバー (LLM 機能)、あなた自身のバックアップターゲット (backup を実行したときのみ)、および初回実行時の Hugging Face からの一度きりのモデルダウンロード。tcpdump、Wireshark、またはネットワークをブロックしたサンドボックスでご自身で検証できます。

スケジューリング

magpie-search index (および任意で backup) をスケジュールで実行します。すぐに使えるユニットが installers/ に用意されています — systemd (Linux)、launchd (macOS)、タスクスケジューラ (Windows) 向けです。

トラブルシューティング

• 「rsync not on PATH」 — scp -r にフォールバックします。Windows では、rsync が同梱されている Git for Windows をインストールしてください。
• 検索が何も返さない — magpie-search stats を実行してください。last_indexed_at が null の場合は、magpie-search index を実行してください。
• --sources web または deepweb が何も返さない — web エクストラがインストールされていません: pip install "magpie-search[web]"。python -c "from magpie_search.providers.web import WebProvider; print(WebProvider().health())" で確認してください — ok: True が望ましい結果です。ok: True なのに結果がまだ空の場合、検索エンジンがあなたのリクエストを拒否しています。これはデータセンターや VPS のアドレス範囲からよくあることです。別のネットワークから試すか、プロバイダーの backends= 設定で別のエンジン順序を設定してください。
• サマライザーが常に degraded — これは設計どおりに偽陽性ガードが機能している状態です。生のトランスクリプトは session SESSION-ID で引き続き利用できます。

---

概要

Magpie Search は VektorGeist LLC が開発しています。

私たちは、自分自身で AI を運用する人々のためのローカルファーストのツールを開発しています。Magpie は検索コアであり、私たちのエージェントプラットフォームは vektorgeist.com にあります。

• ウェブサイト: vektorgeist.com
• 連絡先: [email protected]
• イシューとコントリビューション: このリポジトリでイシューまたは PR を作成してください。

ライセンス

Apache License 2.0 の下でライセンスされています — LICENSE を参照してください。 Copyright © 2026 VektorGeist LLC.

「Magpie Search」およびカササギのマークは VektorGeist LLC の商標です。コードは Apache-2.0 の下でオープンですが、ブランドと名称は留保されています。