mcp-vl-msa-rs

mcp-vl-msa-rs

AI エージェント向けの検索可能な長期メモリを、MCP stdio サーバーとして提供します。 ドキュメント、メモ、過去の会話をコレクションにインデックス化し、クエリに関連する上位 k 個のチャンクを取得して、元のテキストをモデルに注入します。msa_remember / msa_forget でエージェントのメモリを追加・削除できます。純粋な Rust 製で、tantivy による BM25 を採用し、デフォルトのビルドでは ML 依存関係はゼロです。オプションでプロセス内の高密度リランキングも利用できます。

MCP クライアント（Claude Code、Codex、または MCP stdio に対応するもの）なら、どれでも同じメモリを利用できます。クラウドアカウントや埋め込みサービスなしで、セッションやモデルを切り替えても保持される、検索可能なコーパスです。エージェントにナレッジベース、ドキュメントツリー、または独自のチャット履歴を永続的に参照させるために利用できます。埋め込みだけでなく、元のテキストを返す検索機能です。

これは二部構成のメモリの一方です。このサーバーはライブラリ（コーパスの想起）で、対となるmcp-memory-rsはノートブック（厳選された状態）です。エージェントはモデルを切り替えても、どちらも失いません。

flowchart LR
    A["AI agent<br/>(any MCP client)"]
    A -->|"curated state<br/>read / write / sync"| M["mcp-memory-rs<br/><i>the notebook</i>"]
    A -->|"corpus recall<br/>index / search / fetch"| V["mcp-vl-msa-rs<br/><i>the library</i>"]
    M --- D1[("JSON categories<br/>SQLite FTS5")]
    V --- D2[("tantivy BM25<br/>collections")]

名前について：msa は、Memory Sparse Attention 論文（arXiv:2603.23516）から取り入れた検索パターンです。ニューラルモデルではなく、外在的な近似です。MiniMax の MSA アーキテクチャ LLM とは異なります。そちらは内在的な（モデル内の）生成器です。vl は最初の採用者である Vivling（codex-vl）に由来しますが、このサーバーは完全に AI 非依存で、Vivling の要素には一切依存しません。

ステータス：v0.4 — スパース＋高密度のハイブリッドにオプションで対応。

目的

元となるMemory Sparse Attention論文（EverMind-AI）では、チャンク単位でプールされた KV キャッシュに対する、エンドツーエンドで学習可能なスパース・アテンション層を説明しています。これはニューラルな成果物であり、純粋な Rust 製の MCP サーバーには移植できません。移植可能で、このリポジトリが提供を目指すのは、MSA のマクロパターンです。

1. 長文テキストを、小さく固定されたプールサイズ（論文にならい、デフォルトは P=64 語）でチャンク化して保存します。
2. チャンクに対して上位 k 件をスパースにルーティングします（BM25 による代替手法。学習によるルーティングは対象外です）。
3. 元のテキストを注入します（論文 §4.3、アブレーションではこれを除くと -37.1%）。msa_search はチャンクを返し、msa_fetch_doc はドキュメント全体を返します。
4. プロトコルとしてのMemory Interleave（v0.4 で計画中）：AI クライアントがサーバー側カーソルを使ったツール呼び出しの繰り返しを通じて、複数段階の検索を調整します。

設計と根拠はプロジェクトのノート（否定的な結果、ゲートの方法論）に記載されています。詳細はdocs/NEGATIVE_RESULTS.mdを参照してください。

ベンチマーク

検索に関する変更の判断は、絶対スコアではなく、事前登録された対応のある差分とブートストラップ信頼区間に基づきます。ワークロード：HotpotQA（抽出型 QA）、MLDR-it（長文書検索、イタリア語）、LongMemEval-S（会話メモリに関する質問 500 件）。完全な方法論、採用基準、反証された仮説については、docs/NEGATIVE_RESULTS.md をご覧ください。

主な測定結果：

• BM25 はエンジンであり、代用品ではありません。 事前登録された 3 回の試行では、これらのワークロードにおいて、ハイブリッド（BM25 + 高密度リランク）構成は採用基準を超えませんでした。高密度リランクは（デフォルトではオフの）dense_alpha で引き続き利用でき、エンコーダーの改善に合わせて再検証できます。
• 取り込み時のリッチカプセル化（LLM を使わない決定論的な拡張）：すべてのカテゴリで recall@5 が +7～+20。
• 元テキストの注入（msa_search の後に msa_fetch_doc を実行）：スニペットで内容を取得できない層に限って F1 が +14.6。
• 新しさの事前分布は逆効果です。検索スコアではなく、提供時に時間を考慮してください。

再現方法：

crates/msa-bench/scripts/download-bench-datasets.sh   # fetch datasets
scripts/run-baseline-bench.sh                         # BM25 vs BM25+dense sweep
# results land under crates/msa-bench/results/ as JSON

ツールの概要

ツール	追加バージョン	説明
msa_index	v0.1	ドキュメントをインデックス化します。doc_id の既存のチャンクは置き換えられます。
msa_search	v0.1	上位 k 件のチャンクを返します。スコアは 0.0～1.0 に正規化されます。
msa_fetch_doc	v0.1	ドキュメントの元テキスト全体を取得します。
msa_delete	v0.1	ドキュメントとそのすべてのチャンクを削除します。
msa_list_collections	v0.1	レジストリ内で開いているコレクションを一覧表示します。
msa_stats	v0.1	コレクションごとの統計情報（正確な num_documents / total_tokens）を表示します。
SearchFilter	v0.2	メタデータフィルター（where_eq/where_in/created_*）。検索後に適用されます。
msa_search_iterative	v0.3	サーバー側カーソルを使用する Memory Interleave。ラウンドをまたいで重複を除去します。
msa_drop_session	v0.3	TTL 前に Memory Interleave セッションを強制的に退避させます。
msa_search の dense_alpha	v0.4	ハイブリッド BM25 + コサイン類似度によるリランク。--features embeddings と [embeddings] 設定が必要です。
msa_remember / msa_forget	v0.4	エージェントメモリ機能：拡張 + 低シグナル判定 + コンテンツハッシュによる重複排除。標準メタデータ（kind / source_id / created_at）を使用します。
msa_sync_path	v0.4	ディレクトリをコレクションにミラーリングします（ファイルシステムソース、blake3 差分同期）。

インストール

ビルド済みバイナリ（推奨）— 最新リリースからお使いのプラットフォーム向けのアーカイブをダウンロードして展開し、MCP クライアントからバイナリを指定します。

tar xzf mcp-vl-msa-rs-x86_64-unknown-linux-gnu.tar.gz
install -m755 mcp-vl-msa-rs-*/mcp-vl-msa-rs ~/.local/bin/

ビルド済みの対象（Linux + Android）：x86_64-unknown-linux-gnu、x86_64-unknown-linux-musl、aarch64-unknown-linux-gnu、aarch64-unknown-linux-musl（エッジデバイス / ARM / Termux）、aarch64-linux-android。

macOS：ビルド済みバイナリは提供していません（Apple によるコード署名が必要になるためです）。代わりにソースからインストールしてください。以下の cargo install を使えば、署名不要で 1 つのコマンドから Mac 上でコンパイルできます。

ソースからインストール（Rust ツールチェーン）— --locked が必須です（ワークスペースの Cargo.lock に動作する time / tantivy-common の依存関係解決が固定されており、新たに依存関係を解決するとビルドが失敗します）。パッケージ名は mcp-msa-server です（インストールされるバイナリは mcp-vl-msa-rs です）。

cargo install --git https://github.com/DioNanos/mcp-vl-msa-rs \
  --locked --features source-fs mcp-msa-server

ビルドとテスト

cd mcp-vl-msa-rs

# Default: pure BM25, zero network deps
cargo build --release
cargo test

# Hybrid sparse + dense (in-process Candle rerank, no external service)
cargo build --release --features embeddings
cargo test  --features embeddings

ハイブリッドモードの設定

MCP_MSA_CONFIG に [embeddings] を追加すると、密な再ランキングが有効になります。このセクションがない場合、バイナリが --features embeddings を指定してビルドされていても、サーバーは BM25 のみのモードで動作します。

本番用バックエンドは candle-modernbert です。エンコーダーはローカルモデルバンドルを使って、Candle によりプロセス内でオフラインかつ決定的に実行されます。デーモンも実行時のネットワーク接続も、自動ダウンロードも必要ありません。scripts/prepare-granite-r2-97m.sh を使って、バンドルを一度準備してください。

[storage]
storage_dir = "~/.local/state/mcp-vl-msa-rs"

[chunking]
chunk_size = 64
overlap = 0

[embeddings]
backend   = "candle-modernbert"
model_dir = "~/.local/share/mcp-vl-msa-rs/models/granite-r2-97m"
dim       = 768
model_id  = "granite-r2-97m"

移行用の backend = "ollama"（Ollama 互換サービスへの HTTP 接続）も引き続き存在しますが、非推奨であり、v0.6 で削除予定です。これを使って新しい環境を構築しないでください。

AI クライアントは、msa_search（または今後対応するツール）に dense_alpha を渡すことで、呼び出しごとにハイブリッドスコアリングを選択できます。dense_alpha = 1.0（デフォルト）は BM25 のみ、0.0 は密ベクトルのみ、中間値は線形ブレンド α·bm25 + (1-α)·((cos+1)/2) です。BM25 スコアはすでに最大値で正規化されているため、コサイン類似度を [0,1] にシフトして、線形に組み合わせられるようにしています。

MCP stdio として実行

# Default storage: ~/.local/state/mcp-vl-msa-rs/
./target/release/mcp-vl-msa-rs

# With explicit config
MCP_VL_MSA_CONFIG=~/.config/mcp-vl-msa-rs/config.toml \
MCP_DEVICE=my-node \
./target/release/mcp-vl-msa-rs

~/.codex/config.toml の設定例：

[mcp_servers.vl_msa]
command = "/path/to/mcp-vl-msa-rs/target/release/mcp-vl-msa-rs"
env = { MCP_DEVICE = "my-node" }
# let the model call tools without a per-call approval prompt
default_tools_approval_mode = "approve"

Claude Code 用の ~/.claude.json の同等の設定例：

{
  "mcpServers": {
    "vl_msa": {
      "command": "/path/to/mcp-vl-msa-rs/target/release/mcp-vl-msa-rs",
      "env": { "MCP_DEVICE": "my-node" }
    }
  }
}

AI クライアントの互換性

• MCP のサポートが一部に限られるクライアントでは、サーバーの instructions テキストが表示されない場合があります。ツールの説明とリクエストフィールドの説明は、それだけで内容がわかるようになっているため、モデルはそれらのみを参照して動作できます。
• 読み取り専用ツール（msa_search、msa_fetch_doc、msa_stats、msa_list_collections、msa_manifest、msa_search_iterative、msa_interleave_round）には readOnlyHint アノテーションが付いているため、承認ゲートのあるクライアントでは自動承認できます。
• codex でモデルが「unsupported call」または「user cancelled」と報告する場合、これは承認ゲートによるものであり、サーバーの障害ではありません。ツール呼び出しがプロンプトでブロックされないように、（上記の）default_tools_approval_mode を設定してください。

ストレージのレイアウト

~/.local/state/mcp-vl-msa-rs/
├── <collection_a>/        ← tantivy index directory
├── <collection_b>/
└── ...

各コレクションは、独立した tantivy インデックスです。コレクション名は検証され（パス区切り文字や .. などが含まれる場合は拒否されます）、コレクションがルートの外に出ることはありません。

ロードマップ

リリース済み：

• v0.2 — SearchFilter（where_eq / where_in / 作成日時の範囲）、検索後に適用。
• v0.3 — msa_search_iterative による Memory Interleave。サーバー側カーソルと TTL 付き MsaSession レジストリを備えています。
• v0.4 — 機能フラグ embeddings で有効化するハイブリッド BM25 + 密な再ランキング、Ollama バックエンド、呼び出しごとの dense_alpha。エージェントメモリ機能（msa_remember / msa_forget）。インデックス作成時のファイルシステムソースメタデータ（created_at / source / ext / dir）。msa_stats の正確な num_documents / total_tokens。再現可能なベンチマーク用の msa-bench クレート。ビルド済みバイナリのパッケージング。

次の予定（未実装）：

• クエリ時の tantivy フィルター（現在、SearchFilter は検索後に適用されます。通常のコーパスでは問題ありませんが、非常に大きなインデックスで絞り込み率が高い場合は、検索前にフィルターを適用すると有効です）。
• マルチテナントコレクション用 ACL。
• ツールの説明の調整。

関連プロジェクト

• MSA 論文（arXiv:2603.23516）— アーキテクチャ上の着想元（ニューラルで内在的）です。このリポジトリは、マクロパターンを外在的に実装した純粋な Rust による近似です。
• Vivling（codex-vl 内）— 最初の下流利用者です。このサーバーは、その長期記憶として機能します。
• mcp-memory-rs — 厳選されたエージェント状態を扱う連携サーバーです（名前付き JSON カテゴリ、デバイスごとの ACL、フリート同期）。このサーバーはコーパスからの想起を担い、両者を組み合わせることで、厳選されたノートブックと検索可能なライブラリという、エージェントメモリの両面をカバーします。

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。