Gemdex

役立つメモリを一度保存すれば、リポジトリやセッションをまたいで呼び出せます。Gemdex は小さなチャンクをインデックス化して、セマンティック検索と BM25 を組み合わせた正確なマッチングを行い、マッチした項目を親メモリ全体に解決します。MCP エージェントは低コストのタイトルインデックスをスキャンし、必要なメモリだけを開きます。

2 つの実行方法

	ローカル	セルフホスト
エージェント接続	npx gemdex-mcp、stdio	Streamable HTTP /mcp
エンベディング	MLX 経由のデバイス上の EmbeddingGemma 2	マルチモーダル対応を含む、サーバー管理の Gemini
ストレージ	~/.gemdex 内の LanceDB と blob	Postgres/pgvector とファイル/S3 blob
プラットフォーム	Apple Silicon、macOS 14 以降、ネイティブ arm64 Node ≥24	Docker ホスト
人間による管理	localhost サイドカー経由のネイティブ macOS アプリ	Web マネージャー
プール	マシンごとに 1 つ	複数マシンで共有
MCP ツール	削除を含む 7 つ	削除なしの 6 つ

これらは別々のプールです。npx パッケージとデスクトップサイドカーはローカル専用です。セルフホストのプールには HTTP MCP に直接接続してください。

ローカルクイックスタート

npx gemdex-mcp install
claude mcp add gemdex -- npx -y gemdex-mcp@latest

明示的なインストールでは、管理対象の Python/MLX と固定バージョンの mlx-community/embeddinggemma-2-8bit ウェイトがダウンロードされます。ダウンロードサイズは約 1.45 GB、ディスク上では 1.9 GB です。Python、uv、Homebrew、HF CLI、コンパイラーのセットアップは不要です。インストール後、エンベディングはオフラインで実行されます。API キー、センチネル値、プロバイダー切り替えはありません。Rosetta Node はサポートされていません。 MLX モデルとランタイムの要件を参照してください。

インストール前でも 7 つすべてのツールが検出可能で、セットアップ方法を案内します。インストール後にツールを再試行するか、MCP クライアントを再接続してください。

別の MCP クライアントの場合：

{
  "mcpServers": {
    "gemdex": {
      "command": "npx",
      "args": ["-y", "gemdex-mcp@latest"]
    }
  }
}

保存と呼び出し

エージェントに、後で役立つ情報を保存するよう依頼します：

Save how we set up the review workflow to memory.

次に、そのプールを使って別のセッションまたはリポジトリで：

Check memory for our review workflow and use it here.

指示の中で、どのような場合にメモリを使うかをエージェントに伝えます：

## Memory

Use Gemdex recall to find relevant memories before starting work.
Save reusable findings and update existing memories when correcting them.
Report worked/failed/stale outcomes after acting on a fetched memory.
Use read_attachment for transcript bytes.
Delete only when a memory should be permanently removed and the connected
surface provides delete_memory.

MCP ツール

ツール	動作
save_memory	内容や添付ファイル（画像、音声、動画、テキストファイル）を保存し、ID とタイトルを返します
recall	テキストクエリやサンプルメディアファイルを使って検索し、上位 10 件のタイトルと ID を返します。本文全体は返しません
get_memory	親メモリの本文全体、経過期間、添付ファイル、実績を取得します
update_memory	content 全体の置き換え、またはリテラルな edits を行います。タイトルや添付ファイルは任意です
report_outcome	任意のメモとともに、worked、failed、stale を記録します
read_attachment	添付ファイルを UTF-8 テキスト、表示可能な画像、または base64 として読み取ります
delete_memory	Stdio 専用。完全に削除し、クライアント統計をクリーンアップします

タイトルインデックスでの呼び出しではなく、get_memory によって呼び出し回数が増加します。 統計情報は別の台帳に保存されます（デフォルトは ~/.gemdex/stats.json）。 GEMDEX_TRUST_RANKING=true を設定すると、結果を重み付けしたタイトルランキングが有効になります。 それ以外の場合、ランキングは関連性のみで決まります。

ローカルで保存するとき、既存メモリとの類似性が高い場合は通知されます。通知には、すでに計算済みのベクトルとセントロイド類似度を使用します（デフォルトのしきい値は 0.93 です）。 この通知によって保存がブロックされることはありません。GEMDEX_SIMILAR_ON_SAVE と GEMDEX_SIMILAR_THRESHOLD で設定できます。

添付ファイル

ローカルメモリには、画像（PNG、JPEG、WebP、GIF）、音声（WAV、MP3、M4A、 FLAC、AAC、AIFF。最長5分）、動画（MP4、MOV、M4V、WebM）を含めることができます。EmbeddingGemma 2 は各ファイルを端末上でテキストと同じ空間に埋め込むため、画像に何が写っているか、録音で何が話されているかをもとにメモリを見つけられます。想起時にはサンプルファイルも利用できます。 「このスクリーンショットに関する情報がメモリにありますか？」という問いは、テキストクエリの有無にかかわらず機能します。キャプションは任意ですが、キーワードマッチングを追加でき、特に音声で効果があります。テキストファイル（.txt、.json、.jsonl／.ndjson）は、埋め込みを行わない blob として保存されます。メモリごとに、画像8個、音声ファイル4個、動画2個、テキストファイル4個を保存でき、各ファイルの上限は100 MiBです。PDFはローカルではサポートされていません。ローカルの path またはインラインの base64 data と mimeType を使用してください。すべての添付ファイルは read_attachment で読み取れます。

セルフホストサーバーは、Gemini によるマルチモーダル埋め込みと /v1 経由のメディア想起をサポートしています。HTTP MCP の添付ファイル入力はインラインの base64 のみで、クライアントのファイルシステムパスは使用できません。/v1 の仕様を参照してください。

チャット履歴とメモリの整理

ローカルでの消化処理と整理には、既存の Claude Code ログインを使用します。 Claude Code をインストールして claude auth login を実行し、次のコマンドを入力してください。

npx gemdex-mcp status
npx gemdex-mcp ingest-history --source claude --dry-run
npx gemdex-mcp ingest-history --source claude

対象ソースには、Claude Code、Factory CLI、Codex、Antigravity、またはフォルダパスを指定できます。これまでに取り込まれたことのないセッションのみが処理されます。各セッションからダイジェストメモリと、整理済みのトランスクリプト添付ファイルが生成されます。backfill-transcripts は、以前のダイジェストのフッターで参照されているファイルを添付します。--dry-run と --force オプションを使用できます。見つからないファイルはメッセージを表示してスキップされます。

推論は、分離された claude -p --model haiku による構造化 JSON 呼び出しとして実行されます。ツール、設定、スキル、MCP サーバー、フック、CLAUDE.md、セッションの永続化は使用せず、一時的な作業ディレクトリで実行します。同時実行数は4で、呼び出しごとに合計3回まで試行し、タイムアウトは5分です。

コストの見積もりは、Haiku の API 定価相当額（トークン100万個あたり入力$1／出力$5）です。Claude サブスクリプションを利用している場合、使用量はトークンごとの請求ではなく、プランの利用上限に計上されます。ローカル埋め込みは端末上で処理されますが、取り込み対象のトランスクリプトと整理候補は Claude Code の推論に送られます。

整理では、まずローカルベクトルをクラスタリングし、次に Claude Code で候補を判定します。検出結果の削除には人間の承認が必要です。セルフホストでのアップロードには、代わりにサーバーの Gemini による消化処理が使われます。チャット履歴のパスを参照してください。

デスクトップアプリ

ネイティブ macOS アプリでは、ローカルプールを管理できます。メモリの閲覧、検索（テキストまたはファイルによる）、編集、画像・音声・動画の添付とプレビュー、チャット履歴の取り込み、整理結果の確認が可能です。このアプリは gemdex serve と通信します。これは 127.0.0.1 のみで待ち受け、起動ごとにトークンを使用します。その仕様では、明示的な MLX のインストール／移行ジョブと Claude Code の準備状況が公開されます。インストールが完了するまでは、メモリ関連のルートは 503 {needsInstall:true} を返します。取り込み／整理を開始するには、Claude Code の準備が整っている必要があります。サイドカーの仕様を参照してください。

セルフホスト環境では、ウェブマネージャーが人間向けの主要な操作画面です。デスクトップアプリは、そのプールのクライアントではありません。

スタック全体をセルフホストする（1つのコマンド）

curl -fsSL https://raw.githubusercontent.com/nikships/gemdex/main/scripts/install.sh | bash

インストーラーは Postgres、gemdex-server、HTTP MCP、ウェブマネージャーを起動し、シークレットを生成して、マイグレーションの完了を待ち、実際に保存と想起ができることを確認してから、Streamable HTTP クライアントの設定を表示します。Google AI Studio のキーを求めるか、GEMINI_API_KEYを読み込みます。このキーはサーバー用であり、エージェントクライアント用ではありません。

デフォルトではループバック接続のみが許可されます。--lanを指定すると、静的な MCP 認証とログイン不要のウェブアクセスを使って、信頼できる LAN に MCP とウェブを公開します。パブリックアクセスには、HTTPS、Google OAuth、デプロイガイドを使用してください。Postgres や /v1は決して公開しないでください。

{
  "mcpServers": {
    "gemdex": {
      "type": "http",
      "url": "https://gemdex.example.com/mcp"
    }
  }
}

この例は Google OAuth のデプロイを対象としており、クライアントがログインを処理します。

ガイド	目的
セルフホストのデプロイ	Compose、Google OAuth、HTTPS エッジ、公開設定の確認
運用	ストレージ、バックアップと復元、アップグレード、トラブルシューティング
さらに詳しく	DNS、マネージドプラットフォーム、サイジング、コスト
セキュリティ	適用される境界とローンチ前チェックリスト
チャット履歴	ローカル取り込み、ウェブアップロード、OAuth レコードのインポート

パッケージとライブラリの利用

パッケージ	役割
core	MemoryStore、埋め込みプロバイダー、共有 HTTP ルーター、推論
mcp	ローカル stdio ツール、CLI、デスクトップサイドカー
server	BYOI /v1、Postgres/pgvector、Gemini、ファイル/S3 blob
mcp-http	6つのツールを提供する Streamable HTTP エージェント用インターフェース
web	ブラウザマネージャーとセッションアップロード BFF
app	ネイティブのローカルマネージャー

エンジンを直接使用する方法については、core ライブラリの例を参照してください。 ローカル環境の設定はMCP READMEに、 セルフホスト環境の設定はserver READMEに記載されています。

プライバシーと安全性

メモリのテキストと添付ファイルのバイトデータは、独自のストレージ制御を追加しない限り、平文で保存されます。Gemdex には、シークレットのマスキング機能やホスト型のデータ保管サービスはありません。ローカル埋め込みはデバイス上で実行されます。ローカルの取り込みと衛生処理では、アカウントを使って Claude Code 経由で選択したコンテンツを送信します。セルフホストサーバーは、埋め込みのペイロードとアップロードされたセッションの処理データを、そのキーを使って Gemini に送信します。データ保管とセルフホストのセキュリティを参照してください。

ソースからビルドする

Node ≥24 と pnpm ≥10 を使い、リポジトリをクローンしてから実行します。

pnpm install
pnpm build

ローカル MCP のエントリーポイントは packages/mcp/dist/index.jsです。 チェック項目と開発のガイダンスについては、CONTRIBUTING.mdを参照してください。

ライセンス

MIT。LICENSEを参照してください。

MCP レジストリ

mcp-name: io.github.nikships/gemdex