vanguard-memory-node

Vanguard Memory Node (VMN)

Model Context Protocol（MCP）を介して、AI エージェントにローカルで決定論的なメモリを提供します。

クラウド不要。ベクトルデータベース不要。意味のずれもありません。データはお使いのマシン内に保たれます。

---

概要

VMN は、MCP 互換のあらゆる AI エージェントに、ローカルディスクだけに保存される永続的で検索可能なメモリボールトを提供します。テキストは一度だけ取り込まれ、SHA-256 によるコンテンツアドレス指定が行われた後、分割され、シャーディングされた BM25 転置インデックスでインデックス化されます。検索結果は決定論的です。同じデータに対して同じクエリを実行すると、常に同じ順位の結果が返されます。

オプションで、ボールトを ExergyNet LNES-17 ledger と同期し、暗号学的な来歴を保ちながら、デバイスやエージェントをまたいで情報を再検索できます。

---

インストール

npm install -g @lnes/vanguard-memory-node

または、インストールせずに実行できます。

npx @lnes/vanguard-memory-node

---

Claude Desktop との連携

Mac — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "npx",
      "args": ["-y", "@lnes/vanguard-memory-node"]
    }
  }
}

ExergyNet のボールト同期を有効にする場合：

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "npx",
      "args": ["-y", "@lnes/vanguard-memory-node"],
      "env": {
        "EXERGYNET_API_KEY": "sk-exergy-your-key",
        "EXERGYNET_NETWORK": "mainnet",
        "AUTO_SYNC_VAULT": "true"
      }
    }
  }
}

Windows 上の WSL：

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "npx", "-y", "@lnes/vanguard-memory-node"]
    }
  }
}

---

ツール（全 11 種類）

vmn_ingest

テキストを SHA-256 コンテンツアドレス指定のシャードとして保存します。テキストを分割してインデックス化し、ローカルカタログを更新します。

パラメーター	型	必須	説明
text	string	yes	保存するコンテンツ
title	string	no	人が読めるラベル
namespace	string	no	論理パーティション（デフォルト：default）
tags	string[]	no	検索用タグ
content_type	string	no	MIME タイプのヒント（デフォルト：text/plain）
source	string	no	ソースのラベル

戻り値：SHA-256 ルートハッシュ、ボールトのパス、vault_synced フラグ。

vmn_recall

字句 BM25 スコアリングを使用して、指定したシャードから 900 文字のエビデンスウィンドウを取得します。

パラメーター	型	必須	説明
hash	string	yes	vmn_ingest が返すルートハッシュ
query	string	yes	検索クエリ

戻り値：最も一致するエビデンスウィンドウ、または一致するものがないことを示す人が読めるメッセージ。

vmn_search

取り込み済みのすべてのオブジェクトを対象に、ボールト全体をキーワード検索します。スニペット付きの順位付き検索結果を返します。

パラメーター	型	必須	説明
query	string	yes	検索クエリ
limit	number	no	結果の最大件数（デフォルト：10）
namespace	string	no	この名前空間だけに検索対象を限定

vmn_ingest_file

増加するファイルを差分でボールトに取り込みます。カーソルで進捗を追跡し、呼び出しごとに新しい行だけを取り込みます。Stop フックや継続的なログパイプライン向けに設計されており、重複なしで繰り返し安全に呼び出せます。

パラメーター	型	必須	説明
file_path	string	yes	ファイルの絶対パス
session_id	string	no	カーソルキー（デフォルトはファイルパス）
namespace	string	no	取り込むコンテンツの名前空間（デフォルト：file_ingest）
title	string	no	任意のタイトルの上書き
tags	string[]	no	任意のタグ

戻り値：lines_ingested、cursor_line、シャードのhash（新しいコンテンツがない場合は null）。

Stop フックの例 — すべての Claude セッションを自動的に取り込みます。

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "npx -y @lnes/vanguard-memory-node vmn_ingest_file --file_path \"$CLAUDE_SESSION_FILE\" --session_id \"$CLAUDE_SESSION_ID\""
      }]
    }]
  }
}

vmn_list

ボールト内のすべてのメモリオブジェクトを一覧表示します。

パラメーター	型	必須	説明
namespace	string	no	名前空間で絞り込み

vmn_inspect

指定したオブジェクトのカタログメタデータ全体を返します。

パラメーター	型	必須	説明
hash	string	yes	ルートハッシュ

vmn_delete

オブジェクトと、そのすべてのインデックスエントリを完全に削除します。

パラメーター	型	必須	説明
hash	string	はい	ルートハッシュ

vmn_stats

保管庫の集計統計（エントリ数、合計バイト数、名前空間、最古および最新のタイムスタンプ）を返します。

vmn_index_status

現在の BM25 インデックスの状態（READY、REBUILD_REQUIRED、REBUILDING、DEGRADED）を返します。

vmn_rebuild_index

信頼できるオブジェクトファイルから BM25 インデックス全体を再構築します。オブジェクトは変更されないため、いつでも安全に実行できます。

vmn_sync_vault

ローカルのメモリーオブジェクトを ExergyNet LNES-17 保管庫に同期します。EXERGYNET_API_KEY が必要です。EXERGYNET_NETWORK を使って mainnet または testnet を指定します。

パラメーター	型	必須	説明
xlmp_root	string	はい	同期するオブジェクトのルートハッシュ
intent	string	いいえ	同期目的のラベル（デフォルト：manual-sync）

返される値：xlmp_root、bytes_committed、status、解決された保管庫 URL。

---

環境変数

変数	デフォルト	説明
AUTO_SYNC_VAULT	false	true に設定すると、すべての vmn_ingest を ExergyNet に自動同期します
EXERGYNET_API_KEY	—	ExergyNet 保管庫へのアクセス用 API キー（sk-exergy-*）
EXERGYNET_NETWORK	testnet	対象の基盤：mainnet → portal.exergynet.org、testnet → dt.portal.exergynet.org
EXERGYNET_VAULT_URL	( EXERGYNET_NETWORK から解決)	保管庫のベース URL を全面的に上書きします

---

保管庫の構成

~/.vanguard/
├── local_vault/
│   └── <sha256>.txt              # authoritative object files (never modified after write)
├── catalog/
│   └── <sha256>.json             # per-object metadata (O(1) reads)
├── segments/
│   └── <sha256>.json             # segment records with term frequencies
├── cursors/
│   └── <session_id>.json         # cursor state for vmn_ingest_file
└── index/
    └── v2/
        ├── index_manifest.json   # version + state header
        ├── corpus_stats.json     # BM25 corpus statistics
        └── postings/
            └── <2-hex>.json      # 256 sharded posting buckets

---

検索の仕組み

1. 正規化 — Unicode NFC → フレーズエイリアスの置換 → トークン化 → 接尾辞のステミング → ストップワードのフィルタリング → トークンエイリアスの展開
2. ステマー — 13 個のルールを持つ接尾辞除去処理：tions→（5）、ions→（4）、tion→（4）、ings→（4）、ing→（3）、ers→（3）、ies→（3）、ic→（2）、er→（2）、ed→（2）、es→（2）、s→（1）、y→（1）。ルールは長いものから順に適用されます。medications と medication はどちらも同じ語幹になります。
3. エイリアスの展開 — 臨床、技術、法律分野の同義語クラスター（smok↔tobacco↔cigarett、physician↔doctor、hypertens↔bp など）
4. BM25 スコアリング — シャード化された 256 バケットの転置インデックス。高 DF による停滞を抑えるため、各用語の投稿リストは上位 150 件に制限されます
5. フォールバック — BM25 スコアがゼロの場合にステミング済みトークンの集合を比較し、部分一致による誤検出を防止します

---

比較

	VMN	ChromaDB / Pinecone
結果の再現性	同じクエリなら常に同じ結果	モデルのバージョンによって変動
データの保存場所	ローカルディスクのみ	クラウドへのアップロードが必要
クエリごとのコスト	$0	API 使用料
セットアップ時間	60 秒	アカウント + キー + SDK
セマンティックドリフト	なし	モデル更新時に動作しなくなる
オフライン対応	はい	いいえ

---

ライセンス

MIT — 永久に無料、テレメトリーなし、利用制限なし。

ExergyNet が開発しました。