mcp-memory-rs

mcp-memory-rs

純粋な Rust で実装された、ローカルファーストの MCP メモリーサーバーです。AI エージェント向けの、永続的でバージョン管理され、クエリ可能なメモリーです。プラットフォームではなく、ユーザーが所有します。

状態はディスク上に通常の JSON カテゴリとして保存され、SQLite（FTS5）によってインデックス化されます。すべての書き込みにバージョンが付与され、バックアップされます。複数のデバイス間では、Merkle マニフェストと楽観的同時実行制御を備えたオプションの HTTP エンドポイントを通じて同期できます。クラウドアカウントも、埋め込みサービスも、デフォルトモードでのネットワーク依存もありません。

選ばれる理由

ベンダーにひもづいたエージェントのメモリーは、ベンダーのセッションが終了すると失われます。このサーバーは、エージェントの長期的な状態（アイデンティティ、プロジェクト、インフラに関するメモ、デバイスごとのワークフロー）を、自分で読み取り、grep、差分確認、バックアップできるファイルに保持します。どの MCP クライアント（Claude Code、Codex、または MCP stdio に対応するもの）も同じメモリーを利用でき、モデルを切り替えても状態は失われません。

この設計から、次の選択が導かれています。

• ローカルファースト：stdio サーバーは、ローカルストレージを使って完全にオフラインで動作します。 同期は独立した明示的な手順であり、隠れた依存関係にはなりません。
• シンプルなストレージ：カテゴリごとに 1 つの JSON ファイルと SQLite インデックスを使用します。 データベースはファイルから再構築でき、ファイルが正となるデータです。
• デフォルトでバージョン管理：すべての書き込みの履歴を保持し、削除前にはバックアップを作成します。memory_history と memory_compact で履歴の末尾を管理します。
• 同時実行に安全な書き込み：expected_hash により、同時に動作するエージェント間の上書き競合を、明示的な競合として扱います。
• コアに ML を含めない：全文検索には BM25 を備えた SQLite FTS5 を使用します。 memory_search_semantic では、オプションの TF-IDF ハイブリッド検索を追加できます。モデルのダウンロードはありません。

2 つのサーバーの組み合わせ： コーパスの検索（チャンク化されたドキュメント、BM25 検索、 原文の注入）については、姉妹サーバー mcp-vl-msa-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")]

インストール

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

tar xzf mcp-memory-rs-x86_64-unknown-linux-gnu.tar.gz
install -m755 mcp-memory-rs-*/mcp-memory-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 上でコンパイルできます。

cargo install --git https://github.com/DioNanos/mcp-memory-rs --locked

--locked はコミット済みの Cargo.lock を使用します（再現可能なビルド）。

クイックスタート

cargo build --release

# stdio MCP server, offline mode (default)
./target/release/mcp-memory-rs

Claude Code（~/.claude.json）または任意の MCP クライアント：

{
  "mcpServers": {
    "memory": {
      "command": "/path/to/mcp-memory-rs",
      "env": {
        "MCP_MEMORY_CONFIG": "/home/me/.config/mcp-memory-rs/config.toml",
        "MCP_MEMORY_REQUIRE_CONFIG": "1",
        "MCP_MEMORY_MODE": "offline",
        "MCP_DEVICE": "my-laptop"
      }
    }
  }
}

Codex（~/.codex/config.toml）：

[mcp_servers.memory]
command = "/path/to/mcp-memory-rs"
env = { MCP_MEMORY_CONFIG = "/home/me/.config/mcp-memory-rs/config.toml", MCP_MEMORY_REQUIRE_CONFIG = "1", MCP_MEMORY_MODE = "offline", MCP_DEVICE = "my-laptop" }
# auto-approve read-only tools (memory_read/list/search/…); writes still gated
default_tools_approval_mode = "approve"

設定は TOML です。 config/example.toml を ~/.config/mcp-memory-rs/config.toml にコピーして調整してください。サーバーは この XDG 形式のパスを自動検出します。環境変数はファイルの値より優先されます（MCP_DEVICE、 MCP_MEMORY_MODE、MCP_MEMORY_DIR、…）。管理されたデプロイ環境では、 設定がない場合に起動を失敗させるため、MCP_MEMORY_REQUIRE_CONFIG=1 を設定してください。

メモリモデル

メモリはカテゴリ単位で整理されます。カテゴリは名前付きの JSON ドキュメント（base、projects、my-laptop、workflow_my-laptop、…）です。読み取りでは、ドキュメントとメタデータ（コンテンツハッシュ、サイズ、最終書き込み元、タイムスタンプ）が返されます。書き込みではカテゴリを置き換えます。merge=true の場合は、トップレベルのキーごとにパッチを適用します。

アクセス制御

複数デバイスのフリートでは、明示的で小規模な ACL（設定内の [acl]）を使用します。

ルール	効果
admin_devices	一覧にあるデバイスはすべてを書き込みます。
device_categories	デバイス name はカテゴリ name と workflow_name に書き込みます。自身の名前空間のみが対象です。
エージェントのスコープ	デバイス foo-agent は foo_* カテゴリに書き込みます。
全員	すべてのデバイスがすべてを読み取れます。

管理者以外の書き込み元は、不明なカテゴリへのアクセスを拒否されます。つまり、デフォルトでアクセスを許可しません。

フリート同期

各ノードはローカル優先で動作します。1つ以上のノードが HTTP API を同期用リモートとして公開します。sync_manifest はすべてのカテゴリのマークルルート付きフィンガープリントを作成し、sync_diff はマニフェストを比較し、memory_sync は変更のあるカテゴリをプッシュするか、リモートの変更をプルします。ノード間の競合は、設定された conflict_strategy（デフォルトは最終書き込み優先）で解決されます。expected_hash の事前条件は直接の書き込み（MCP と HTTP）を保護しますが、同期エンベロープには適用されません。

HTTP API は管理者／同期プレーンです。ベアラートークンを使うと、すべてのカテゴリにフルアクセスできます。カテゴリごとの ACL が適用されるのは、デバイスの ID をローカルで特定できる MCP stdio サーフェスです。HTTP の呼び出し元は共有トークンによってのみ識別されるため、HTTP ではデバイスごとの ACL は適用されません。

HTTP サーバーを起動するには MCP_MEMORY_TOKEN が必須であり、設定されていない場合は起動を拒否します。ループバック（デフォルト）にバインドし、ノード間はトンネルで接続してください。パブリックインターネットには公開しないでください。

MCP_MEMORY_TOKEN=<secret> ./target/release/mcp-memory-rs --http

ツールサーフェス

ツール	説明
memory_read	カテゴリを読み取ります（フィールドによる任意のフィルタリングに対応）。
memory_write	カテゴリを置き換えるか、マージパッチを適用します。バージョン管理に対応し、expected_hash の事前条件を使用します。
memory_append	有界の追記専用ログカテゴリに、タイムスタンプ付きのエントリを追加します。max_entries／max_age_days に基づいて古いエントリを自動削除します。イベントストリームやセッションジャーナルに使用することで、メモリカテゴリの肥大化を防ぎます。
memory_delete	カテゴリを削除します（先にバックアップを作成します）。
memory_list	すべてのカテゴリを、ハッシュ、サイズ、最終更新のメタデータとともに一覧表示します。
memory_search	FTS5 全文検索。BM25 ランキング、カテゴリ／日付／実行者によるフィルタリング、スニペットに対応します。
memory_search_semantic	TF-IDF と FTS5 を組み合わせたハイブリッド検索です。
memory_history	カテゴリのバージョン履歴を表示します。
memory_delta	既知のハッシュ以降の変更を返します（低コストなポーリング）。
memory_context	複数カテゴリをウォームアップのために読み取ります。トークン予算を考慮します。
memory_compact	古いバージョンとバックアップを削除します。
memory_status	ローカル優先のステータスを表示します。変更キュー、マニフェストハッシュ、最終同期が含まれます。
memory_doctor	パス、データベース、カテゴリ、同期設定を診断します。
sync_manifest	すべてのカテゴリのマークルルート付きマニフェストを作成します。
sync_diff	ローカルとリモートのマニフェストを比較し、プッシュ／プル／競合の各セットを返します。
sync_push / sync_pull	同期エンベロープをエクスポート／インポートします。
memory_sync	設定済みのリモートに対して、1回の同期ステップを実行します（push_dirty／pull_remote）。

MCP 以外のコンシューマー向けに、同じサーフェスを HTTP（/api/v1/*）でも利用できます。/health は認証不要ですが、それ以外のエンドポイントにはベアラートークンが必要です。

AI クライアントとの互換性

このサーバーは、性能の低いクライアントモデルにも自明に理解できるように構築されています。

• initialize 時に、メモリモデルとエントリーポイントとなるツールを説明する instructions 文字列を返します。一部の軽量クライアントはこのフィールドを無視します。クライアントに表示されない場合は、代わりにツールの説明を確認してください。同じガイダンスが記載されています（例：memory_read が受け取るのは key ではなく category です）。
• 読み取り専用ツールには readOnlyHint の注釈が付いているため、Codex などのクライアントでは自動承認できます。Codex で unsupported call ／ user cancelled という結果が返る場合、通常はサーバーの障害ではなく、ツール承認ゲートが作動したことを意味します。default_tools_approval_mode = "approve" を設定してください（上記の Codex スニペットを参照）。
• サーバーは標準の MCP ハンドシェイクを使用します。クライアントは、他の MCP クライアントと同様に、initialize を完了して notifications/initialized を送信する必要があります。

ストレージのレイアウト

設定がなく、厳格モードが無効の場合、スタンドアロンの base_dir は互換性のため引き続き ~/.memory になります。自動検出されるサンプル設定では、XDG 形式の ~/.local/state/mcp-memory-rs が使用されます。設定の解決順序は、明示的な MCP_MEMORY_CONFIG、$XDG_CONFIG_HOME、$HOME/.config、従来の cwd 内にある memory-config.toml、その後にスタンドアロンのデフォルトです。いずれの場合も、レイアウトは次のとおりです。

<base_dir>/
├── categories/   # one .json file per category — the source of truth
├── backups/      # automatic pre-delete/pre-overwrite backups
├── memory.db     # SQLite: FTS5 index, versions, sync state (rebuildable)
└── memory.db-wal # write-ahead log (WAL mode; do not copy or delete by hand)

並行処理（複数のプロセスで1つのストアを共有）

すべての書き込みプロセス（クライアントごとに1つの stdio サーバーと、任意の --http インスタンス）は、同じファイルに対してそれぞれ独自の SQLite 接続を開きます。0.3.2 以降、各 変更処理は BEGIN IMMEDIATE トランザクション内で実行されます。SQLite がプロセス間の書き込みを 直列化するミューテックスとなるため、追記（読み取り → 変更 → 書き込み）で他のプロセスのエントリーが 失われることはありません。ロックの取得は、合計の制限時間内でジッター付きバックオフを用いて再試行されます。制限時間を超えると、処理がハングしたりデータが破損したりする代わりに、明確な Store busy … retry later エラーで呼び出しが失敗します。

[storage]
journal_mode = "wal"           # "wal" (default) or "delete"
synchronous = "full"           # "full" (default, durable) or "normal"
sqlite_busy_timeout_ms = 200   # per-statement SQLite busy handler
lock_deadline_ms = 10000       # total wait for the write lock per mutation

カテゴリの JSON ファイルは、クラッシュ時の安全性を確保して書き込まれます。新しい内容はファイルの隣に（一意のトランザクション名で）一時保存され、SQLite の行が コミットされた後、一時保存ファイルが所定の場所にリネームされます。その間にプロセスが 終了すると、一時保存ファイルが残ります。その扱いは次回の書き込みロック時にハッシュで決まります（コミット済みのハッシュと一致する場合は昇格され、それ以外の場合は破棄されます）。 読み取りではリネームも削除も行われません。コミット済みハッシュを持つファイルが読み取られます。memory_write merge=true、ログ／メモリの種類チェック、任意の expected_hash による compare-and-swap は、すべて同じロック内で実行されます。

スナップショットと復元

memory.db だけではバックアップになりません（WAL、JSON ファイル）。CLI を使用してください。

mcp-memory-rs --snapshot /path/to/snap-2026-09-15 --with-backups  # db + json + backups + manifest
mcp-memory-rs --restore  /path/to/snap-2026-09-15 --stopped
mcp-memory-rs --verify-store                                      # read-only: db vs json, pending files

--verify-store は Store を開かないため（PRAGMA、スキーマ、照合を行いません）、別のバイナリが引き続き所有しているストアに対しても安全に実行できます。0.3.2 より前のバージョンで書き込まれたストアでは、データベースの行より新しいファイルを持つカテゴリが存在することがあります（SQL 書き込みに失敗したケース）。--adopt-json --plan out.json は対象を読み取り専用で記述し、--adopt-json --apply out.json は前提条件を確認したうえで、ロック内でファイルを取り込みます。復元の最後の入れ替えは数回のリネームで行われます。コピーには安全ですが、全体としてアトミックではありません。RESTORE_IN_PROGRESS マーカーにより、手動で中断された入れ替えから復旧するまでストアは閉じたままになります。

スナップショットの作成中は書き込みがブロックされます（読み取りは継続します）。VACUUM INTO を実行してカテゴリファイルをコピーするため、両方の内容は同じ時点の状態を示します。報告前に検証も行われます。対象範囲は manifest.json に明示されます。--with-backups を指定しない場合、対象は現在の内容とバージョンの メタデータ のみです。 memory_history のペイロード（read_version）は backups/ に保存されているため、対象に含めるには --with-backups が必要です。復元では、何かに触れる 前に スナップショットを検証します（整合性、記録されたハッシュと一致するカテゴリごとに1ファイル）。その後、稼働中のストアを置き換え、以前のストアを <base_dir>/restore-parked-<timestamp>/ に退避します。そのストアを使用するすべての mcp-memory-rs プロセスを、事前に停止する必要があります。--stopped フラグは、その確認を示すものです。

ビルドとテスト

cargo build --release   # single static-friendly binary
cargo test              # unit + integration tests
cargo clippy --all-targets -- -D warnings

ビルド時にネットワークアクセスは不要で、同梱の SQLite 以外に C 依存関係はありません。

ライセンス

Apache-2.0。詳細は LICENSE をご覧ください。