Memory Mcp 1file

https://github.com/tenatarika/vex をご利用ください

🧠 Memory MCP サーバー

AI エージェント向けに、永続的で意味的な検索が可能なグラフベースのメモリを提供する、高性能な純粋な Rust 製の Model Context Protocol（MCP）サーバーです。

以下と問題なく連携します。

• Claude Desktop
• Claude Code（CLI）
• Gemini CLI
• OpenAI Codex（CLI／IDE）
• Cursor
• OpenCode
• Cline／Roo Code
• その他、MCP に準拠するあらゆるクライアント。

🏆 「オールインワン」の強み

複雑なスタック（Python + ベクトル DB + グラフ DB）が必要な他のメモリソリューションとは異なり、このプロジェクトは単一の自己完結型実行ファイルです。

• ✅ 外部データベース不要（SurrealDB を組み込み済み）
• ✅ API キー不要、クラウド不要、Python 不要 — 組み込み ONNX ランタイムを介して、すべてが完全にローカルで動作します。埋め込みモデルはバイナリに組み込まれ、CPU 上で実行されます。データがマシンの外部に送信されることはありません。
• ✅ セットアップ不要（Docker コンテナまたはバイナリを 1 つ実行するだけです）

次の機能を組み合わせています。

1. 意味的な類似性を検索するベクトル検索（FastEmbed）。
2. エンティティ間の関係を扱うナレッジグラフ（PetGraph）。
3. コードベースを深く理解するための、シンボルグラフ（呼び出し、継承、実装）を含むコードインデックス作成。
4. 最適な結果を得るためのハイブリッド検索（Reciprocal Rank Fusion）。

🏗️ アーキテクチャ

graph TD
    User[AI Agent / IDE]
    
    subgraph "Memory MCP Server"
        MS[MCP Server]
        
        subgraph "Core Engines"
            ES[Embedding Service]
            GS[Graph Service]
            CS[Codebase Service]
        end
        
        MS -- "Store / Search" --> ES
        MS -- "Relate Entities" --> GS
        MS -- "Index" --> CS
        
        ES -- "Vectorize Text" --> SDB[(SurrealDB Embedded)]
        GS -- "Knowledge Graph" --> SDB
        CS -- "AST Chunks" --> SDB
    end

    User -- "MCP Protocol" --> MS

詳細なアーキテクチャドキュメントはこちら

---

MCP プロトコルとトランスポート

サーバーは rmcp 3.2 を使用し、次の 2 つのプロトコルライフサイクルをサポートしています。

• MCP 2026-07-28 のステートレスリクエスト： クライアントは server/discover から開始できます。すべてのリクエストには、プロトコルバージョンとクライアントの メタデータが _meta に含まれます。プロセスは MCP セッション、Mcp-Session-Id、 変更可能な currentProject を保存しません。
• MCP 2025-11-25 との互換性： 従来の initialize／initialized ライフサイクルを使用するクライアントも引き続きサポートされます。

このバイナリは stdio 経由で MCP を公開します。ローカルワークスペースごとに 1 つのプロセスを実行し、 Docker を使用する場合はそのワークスペースを /project にマウントしてください。Streamable HTTP は このリリースでは有効化も告知もされていないため、HTTP セッション管理や共有サーバーの認証対象領域はありません。コードインデックス作成では index_project を介して明示的なパスを指定します。1 つのプロセスに複数のプロジェクトをインデックス登録している場合、コード検索は project_id で絞り込めます。Roots ネゴシエーションは使用されません。

---

🤖 エージェントとの連携（システムプロンプト）

エージェントがメモリを確認しなければ、メモリは役に立ちません。「長期記憶」の効果を得るには、厳格なプロトコルに従うようエージェントに指示する必要があります。

実戦で十分に検証された メモリプロトコル（AGENTS.md） を用意しています。必要に応じて調整してご利用ください。

🛡️ コアワークフロー（コンテキストの保護）

このプロトコルは、コンテキストウィンドウの圧縮やセッションの再起動に対応するための、具体的なフローを実装しています。

1. 🚀 セッション開始：エージェントは、直ちに TASK: in_progress を検索する必要があります。これにより、前回のセッション終了時またはコンテキスト圧縮前に行っていた作業の全コンテキストが復元されます。
2. ⏳ 自動続行：エージェントが見つかったタスクをユーザーに提示して応答を待つ（または自動で続行する）安全機構です。これにより、新しいタスクを幻覚してしまうのを防ぎます。
3. 🔄 トリプル同期：メモリ、ToDo リスト、ファイルを同時に更新します。いずれかに問題が発生した場合（例：コンテキストの喪失）、残りがバックアップとして機能します。
4. 🧱 プレフィックスシステム：すべてのメモリにプレフィックス（TASK:、DECISION:、RESEARCH:）を付けることで、セマンティック検索の対象を適切な情報の種類に絞り、ノイズを減らします。

これらのワークフローにより、エージェントは「ステートレスなチャットボット」から、再起動やコンテキストのクリア後も作業を続けられる「ステートフルなワーカー」へと変わります。

推奨されるシステムプロンプトのスニペット

IDE 固有のファイル（.cursorrules など）に指示を分散させるのではなく、AGENTS.md を信頼できる唯一の情報源として設定します。

エージェントのベースシステムプロンプトで、次のように指示します。

1. 各セッションの開始時に AGENTS.md を読む。
2. そこに定義された プロトコルに従う。

この動作を開始するための最小限の参考プロンプトを次に示します。

# 🧠 Memory & Protocol
You have access to a persistent memory server and a protocol definition file.

1.  **Protocol Adherence**:
    - READ `AGENTS.md` immediately upon starting.
    - Strictly follow the "Session Startup" and "Sync" protocols defined there.

2.  **Context Restoration**:
    - Run `search_text("TASK: in_progress")` to restore context.
    - Do NOT ask the user "what should I do?" if a task is already in progress.

なぜ重要なのでしょうか？

このプロトコルがなければ、コンテキストの圧縮やセッションの再起動後にエージェントはコンテキストを失います。このプロトコルがあれば、現在のタスクの全コンテキストが維持され、チャット履歴がクリアされても、手順や詳細が失われることはありません。

---

🔌 クライアントの設定

Docker の汎用設定（あらゆる IDE／CLI）

この MCP サーバーを任意のクライアント（Claude Code、OpenCode、Cline など）で使用するには、次の形式の Docker コマンドを使用します。

主な要件：

1. メモリボリューム：-v mcp-data:/data（グラフ、埋め込み表現、キャッシュ済みモデルの重みを保持します）
2. プロジェクトボリューム：-v $(pwd):/project:ro（サーバーがコードを読み取り、インデックス化できるようにします）
3. 初期化プロセス：--init（サーバーを確実に正常終了させます）

ヒント

1 つのボリュームですべてを保持できます：単一の -v mcp-data:/data マウントで、SurrealDB データベースと約 1.2 GB の埋め込みモデル（/data/models/ に保存）の両方をカバーします。/data/models 用に別のボリュームを用意する必要はありません。これはすでに /data のサブディレクトリであり、自動的に保持されます。名前付きボリュームを使用しない場合、Docker は docker run のたびに新しい匿名ボリュームを作成するため、実行するたびにモデル（約 1.2 GB）を再ダウンロードすることになります。

JSON 設定（Claude Desktop など）

設定ファイル（例：claude_desktop_config.json）に次を追加します。

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run",
        "--init",
        "-i",
        "--rm",
        "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "/absolute/path/to/your/project:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

注： /absolute/path/to/your/project は、インデックス化する実際のパスに置き換えてください。Cursor や VSCode 拡張機能など、一部の環境では ${workspaceFolder} のような変数を使用できる場合がありますが、Docker では絶対パスが最も確実です。

Cursor（個別の手順）

1. Cursor Settings > Features > MCP Servers に移動します。
2. + Add New MCP Server をクリックします。
3. タイプ：stdio
4. 名前：memory
5. コマンド：

   docker run --init -i --rm --memory=3g -v mcp-data:/data -v "/Users/yourname/projects/current:/project:ro" ghcr.io/pomazanbohdan/memory-mcp-1file:latest
   

   (コードのインデックス化が必要な場合は、ワークスペースを切り替えるときにプロジェクトのパスを更新してください)

OpenCode／CLI

docker run --init -i --rm --memory=3g \
  -v mcp-data:/data \
  -v $(pwd):/project:ro \
  ghcr.io/pomazanbohdan/memory-mcp-1file:latest

NPX／Bunx（Docker 不要）

npx または bunx を使用して、サーバーを直接実行できます。npm パッケージが、お使いのプラットフォームに適したコンパイル済みバイナリを自動的にダウンロードします。

Claude Desktop

claude_desktop_config.json に次を追加します。

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Claude Code（CLI）

claude mcp add memory -- npx -y memory-mcp-1file

Cursor

1. Cursor Settings > Features > MCP Servers に移動します。
2. + Add New MCP Server をクリックします。
3. Type：command
4. Name：memory
5. Command：npx -y memory-mcp-1file

または、.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Windsurf / VS Code

MCP の設定に追加します。

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

Bun

{
  "mcpServers": {
    "memory": {
      "command": "bunx",
      "args": ["memory-mcp-1file"]
    }
  }
}

OpenAI Codex CLI（プロジェクトスコープ）

このリポジトリには、信頼済みプロジェクト用の .codex/config.toml が含まれています。この設定は、ローカル STDIO 経由で [email protected] を起動し、データを .codex/data に保存して、 16 個のツールをプロジェクトの許可リストとして公開します。破壊的なツールである delete_memory、delete_project、reset_all_memory は、意図的にプロジェクト設定から 除外されています。ネイティブの Codex インデックス作成は、MEMORY_MCP_ALLOWED_INDEX_ROOT によって 現在のリポジトリ内に制限されています。

プロジェクトスコープの Codex 設定は、リポジトリを明示的に信頼した後にのみ読み込まれます。 Windows では、まずパッケージを個別に確認してください。

npx -y [email protected] -- --help

次に、リポジトリから codex を実行し、以下でサーバーを確認します。

/mcp

または：

codex mcp list
codex mcp get memory

required = true の設定により、Memory MCP の起動に失敗した場合に、メモリのワークフローを使わず プロジェクトがサイレントに実行されるのではなく、失敗が表示されます。 ツールの許可リストは、Codex が読み込む MCP ツールを制御します。プロセスの サンドボックスではありません。この設定を有効にする前に、リポジトリと npm パッケージを信頼してください。

注： Docker とは異なり、npx／bunx はバイナリをローカルで実行するため、すでにファイルシステムにアクセスできます。ディレクトリのマウントは不要です。データの保存先をカスタマイズするには、args 経由で --data-dir を渡します。

"args": ["-y", "memory-mcp-1file", "--", "--data-dir", "/path/to/data"]

Gemini CLI

~/.gemini/settings.json に追加します。

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "memory-mcp-1file"]
    }
  }
}

または Docker を使います。

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": [
        "run", "--init", "-i", "--rm", "--memory=3g",
        "-v", "mcp-data:/data",
        "-v", "${workspaceFolder}:/project:ro",
        "ghcr.io/pomazanbohdan/memory-mcp-1file:latest"
      ]
    }
  }
}

---

✨ 主な機能

• セマンティックメモリ：テキストをベクトル埋め込み（デフォルトは granite）とともに保存し、「雰囲気に基づく」検索を実現します。
• グラフメモリ：エンティティ（User、Project、Tech）とその関係（uses、likes）を追跡します。PageRank ベースのトラバーサルをサポートします。
• コードインテリジェンス：Rust、Python、TypeScript、JavaScript、Go、Java、Dart/Flutter のローカルプロジェクトディレクトリを（AST ベースのチャンク化で）インデックス化します。シンボル間の 呼び出し、インポート、継承、実装、ミックスイン の関係を追跡します。
• 時間的な有効性：メモリには valid_from と valid_until の日付を設定できます。
• SurrealDB バックエンド：高速な組み込み型の単一ファイルデータベースです。

---

🛠️ 利用可能なツール

サーバーは AI モデルに 19 個のツールを公開し、論理的なカテゴリに分類しています。

🧠 コアメモリ管理

ツール	説明
store_memory	内容と任意のメタデータを指定して、新しいメモリを保存します。
update_memory	メモリのフィールドを更新します。
delete_memory	ID でメモリを削除します。
list_memories	メモリを一覧表示します（新しい順）。
get_memory	ID でメモリの全内容を取得します。
invalidate	メモリをソフト削除し、任意で置き換え先を関連付けます。
get_valid	有効なメモリを取得します。特定時点でのクエリには、任意で timestamp（ISO 8601）を指定します。

🔎 検索と取得

ツール	説明
recall	ハイブリッド検索（ベクトル＋キーワード＋RRF によるグラフ検索）。メモリ検索のデフォルトです。
search_memory	メモリを検索します。mode は vector（デフォルト）または bm25 です。

🕸️ ナレッジグラフ

ツール	説明
knowledge_graph	KG 操作を統合します。action は create_entity | create_relation | get_related | detect_communities です。

💻 コードベースインテリジェンス

ツール	説明
index_project	コード検索用にコードベースのディレクトリをインデックス化します。
delete_project	インデックス化されたプロジェクトを削除します。
recall_code	コードを取得します。mode は vector または hybrid（デフォルト）です。ハイブリッド検索では、ベクトル＋BM25＋グラフを融合します。
search_symbols	名前でコードシンボルを検索します。
symbol_graph	シンボルグラフをたどります。action は callers | callees | related です。
project_info	プロジェクト情報を取得します。action は list | status | stats です。

⚙️ システムとメンテナンス

ツール	説明
get_status	システムのステータスと起動の進捗状況を取得します。
reset_all_memory	危険：すべてのデータベースデータをリセットします（confirm=true が必要です）。
how_to_use	ツールの使用例とパラメーターの組み合わせを表示します。

---

⚙️ 設定

環境変数または CLI 引数：

引数	環境変数	デフォルト	説明
--data-dir	DATA_DIR	./data	DB の保存場所
--model	EMBEDDING_MODEL	granite	埋め込みモデル（granite、e5_multi、qwen3、gemma、bge_m3、nomic、e5_small）
--mrl-dim	MRL_DIM	(ネイティブ)	MRL 対応モデルの出力次元数（例：Qwen3 の場合は 64、128、256、512、1024）。デフォルトはモデルのネイティブな最大次元数です（Granite は 384、Qwen3 は 1024）。
--batch-size	BATCH_SIZE	8	埋め込み推論の最大バッチサイズ
--cache-size	CACHE_SIZE	1000	埋め込み用 LRU キャッシュの容量
--timeout	TIMEOUT_MS	30000	タイムアウト（ミリ秒）
--idle-timeout	IDLE_TIMEOUT	0	アイドルタイムアウト（分）。0 = 無効
--log-level	LOG_LEVEL	info	ログの詳細度
(なし)	HF_TOKEN	(なし)	HuggingFace トークン（gemma などのアクセス制限付きモデルでのみ必要です）
(なし)	EMBEDDING_QUEUE_CAPACITY	256	バックグラウンド埋め込みキューの最大サイズ
(なし)	EMBEDDING_BATCH_SIZE	8	1 回の埋め込み処理チャンクで処理するファイル数
(なし)	INDEX_BATCH_SIZE	20	1 回の増分処理チャンクで処理するファイル数
(なし)	INDEX_DEBOUNCE_MS	2000	インデックスイベントをフラッシュするまでの待機時間（ミリ秒、デバウンス）
(なし)	MANIFEST_DIFF_INTERVAL_MINS	10	不足ファイルを定期確認する間隔（分）

🧠 利用可能なモデル

--model 引数または EMBEDDING_MODEL 環境変数を使って、埋め込みモデルを切り替えられます。

どちらも指定されていない場合、バイナリは Granite を使用します。設定の優先順位は次のとおりです。 明示的な --model 引数、EMBEDDING_MODEL、組み込みの Granite デフォルト値の順です。

引数の値	HuggingFace リポジトリ	次元数	サイズ	用途
granite	ibm-granite/granite-embedding-97m-multilingual-r2	384	~195 MB	デフォルト。ModernBERT と CLS プーリングを使用した、多言語およびコード検索向けモデルです。
e5_multi	intfloat/multilingual-e5-base	768	1.1 GB	従来の多言語モデルで、品質とパフォーマンスのバランスに優れています。
qwen3	Qwen/Qwen3-Embedding-0.6B	1024 (MRL)	1.2 GB	2026 年最高水準のオープンソースモデル。32K コンテキスト、MRL 対応です。
gemma	onnx-community/embeddinggemma-300m-ONNX	768 (MRL)	~195 MB	MRL に対応した、より軽量な代替モデルです。（独自ライセンス契約が必要です）
bge_m3	BAAI/bge-m3	1024	2.3 GB	最先端の多言語ハイブリッド検索に対応します。高負荷です。
nomic	nomic-ai/nomic-embed-text-v1.5	768	1.9 GB	高品質で、長いコンテキストに対応する BERT 互換モデルです。
e5_small	intfloat/multilingual-e5-small	384	134 MB	最速で、必要な RAM も最小限です。開発やテストに適しています。

granite は、ネイティブの 384 次元で L2 正規化された CLS 埋め込みを生成します。現在の Candle CPU パスでは、二次的なアテンションのメモリーコストを抑えるため、入力を 512 トークンに制限しています。モデル自体は最大 32K トークンに対応しています。

📉 Matryoshka Representation Learning (MRL)

（MRL） と記されたモデルでは、出力埋め込みベクトルをより小さな次元数（例：512、256、128）に動的に切り詰めても、精度の低下を最小限に抑えられます。これにより、データベースのストレージを節約し、ベクトル検索を高速化できます。

希望するサイズを指定するには、--mrl-dim 引数を使用してください。省略した場合は、モデルのネイティブな基本次元数（例：Qwen3 の場合は 1024）がデフォルトになります。

警告： 特定の次元数でデータベースを作成すると、データディレクトリを消去せずに次元数を変更することはできません。

🔒 ゲート付きモデルと認証（Gemma）

デフォルトでは、サーバーは Apache 2.0 ライセンスのモデルである Granite を使用します。認証なしで自動的にダウンロードされます。

ただし、Gemma（--model gemma）を使用する場合は、プロプライエタリライセンスの「ゲート付きモデル」であるため、認証が必要です。

Gemma を使用するには：

1. Hugging Face の google/embeddinggemma-300m にアクセスします。
2. ログインして、**「Agree to access repository」**をクリックします。
3. HF Tokens でアクセストークンを生成します（読み取り権限で十分です）。
4. トークンを指定してサーバーを起動します。

# Using environment variable
HF_TOKEN="hf_your_token_here" memory-mcp --model gemma

# Or via .env file (see .env.example)

警告

モデルの変更とデータの互換性

新規インストールでは、デフォルトで granite（384 次元）が使用されます。e5_multi（768 次元）で作成された既存のデータディレクトリは、--model e5_multi を明示的に指定して起動した場合にのみ引き続き使用できます。

次元数の異なるモデルに切り替えるには、新しいデータディレクトリ（または消去したボリューム）と、インデックスの完全な再作成が必要です。

次元数が同じモデル間（例：e5_multi <-> nomic）の切り替えも、意味空間が異なるため推奨されません。

🔮 今後のロードマップ（研究とアイデア）

Hindsight などの高度なメモリシステムの分析に基づき（これらのメカニズムの詳細は、同システムのドキュメントを参照してください）、今後のリリースに向けて以下の「認知アーキテクチャ」機能を検討しています。

1. メタ認知的な振り返り（統合）

• 問題： 生のメモリには、時間とともにノイズが蓄積します（例：同じバグの修正について、個別のメモリが 10 件蓄積される）。
• 解決策： 最近のメモリを定期的にスキャンする reflect バックグラウンドプロセス（またはツール）を実装します。
  • 冗長な項目を重複排除します。
  • 矛盾を解決します（2 つのメモリが矛盾する場合は、新しい方を残すか、確認用にフラグを付けます）。
  • 低レベルの事実を統合し、より高次の「インサイト」を生成します（例：5 つのコード上の選択から「ユーザーは Python より Rust を好む」と導き出します）。

2. 時間減衰と「プレゼンス」

• 問題： 古いメモリが、セマンティック検索で現在のコンテキストを覆い隠すことがあります。
• 解決策： Reciprocal Rank Fusion（RRF）アルゴリズムに時間減衰を組み込みます。
  • 「現在の状態」を示唆するクエリでは、最近のメモリに計算されたブーストを付与します。
  • エージェントが「履歴アーカイブ」よりも「ワーキングメモリ」を動的に優先できるようにします。

3. 名前空間付きメモリバンク

• 現在の境界： コードインデックスでは project_id による明示的な 絞り込みがすでにサポートされていますが、メモリレコードはプロセス全体で共有されます。
• 今後の作業： 名前空間／プロジェクトのスコープをメモリとグラフの 操作にも拡張し、1 つの共有サーバーで複数のエージェントワークスペースを分離できるようにします。

4. 認識論的確信度スコア

• 問題： エージェントは推測と検証済みの事実を同じように扱います。
• 解決策： メモリスキーマに confidence スコア（0.0 - 1.0）を追加します。
  • 仮説を保存できるようになります（「バグは auth.rs にあると思う」、confidence：0.3）。
  • 検索ツールは、事実に関する質問に回答する際、確信度の低いメモリを除外できます。

---

ライセンス

MIT