Mem Reduct

memreduct-mcp

Windows 上で AI エージェント（Claude Code、Codex、Cursor、Claude Desktop…）が**自分の Mem Reduct**を使って RAM を解放できるようにします。今すぐメモリを必要としているモデル、レンダリング、ビルドにメモリを割り当てられます。管理者権限の確認も、クリックして閉じるダイアログも必要ありません。

中文说明

理由

Windows 上の AI エージェントは、ビルド、モデル推論、レンダリング、複数のセッションや MCP サーバーの同時実行など、長時間のジョブを自ら実行します。その間にメモリはいっぱいになりますが、エージェントにはメモリを解放する方法がありません。アイドル状態のセッションはページをメモリ上に保持し続け、ほかのプログラムのメモリを解放するには、エージェントが持っていない管理者権限が必要です。Mem Reduct なら実行できますが、人がクリックしたときに限られます。

memreduct-mcp がこの問題を解決します。すでに実行している Mem Reduct が、エージェントが必要とするタイミングでクリーンアップを行い、何が起きたかをエージェントに知らせます。

仕組み

Mem Reduct はすでに管理者権限でトレイに常駐しています。このサーバーは Mem Reduct のメモリクリーンアップ用ホットキーを押します。Windows は、管理者権限のないエージェントからの操作でも、登録済みホットキーを管理者権限で実行中の Mem Reduct に送信するため、UAC の確認、スケジュールされたタスク、管理者サービスは必要ありません。その後、サーバーは Mem Reduct がクリーンアップを記録するまで待機し（ini 内の StatisticLastReduct）、実行前後の使用可能 RAM を計測します。

ホットキーによるクリーンアップでは、確認メッセージもモーダルダイアログも表示されません。そのため、このサーバーは memreduct.exe -clean を使用しません。コマンドラインを使うと、必ず誰かがクリックしなければならないメッセージボックスが表示されるからです。

このプロジェクトに Mem Reduct は含まれていません。Mem Reduct は Henry++ による GPL-3.0 ソフトウェアです。このサーバーはホットキーを押すだけです。

クリーンアップのタイミング

エージェントはメモリ不足を感じ取れず、指示を書くだけでは不十分です。14 時間の動画ジョブでは、このサーバーの指示を受けたエージェントは自発的にクリーンアップしませんでした。その間、PC の使用可能メモリは 75 分間にわたって 1 GB 未満でした。そのため Claude Code では、プラグインにフックも付属しており、エージェントの各ステップで実行されます。

タイミング	動作
負荷の高い作業（サブエージェント、ワークフロー、バックグラウンドジョブ、ビルド、レンダリング）の前に、使用可能メモリが 25% 未満	先にクリーンアップします。負荷がかかると、計測された解放量は数分以内に減少するため、このタイミングが重要です。
ツールがメモリ不足エラー（GPU メモリを除く）で失敗したとき	クリーンアップし、再試行してよいとエージェントに伝えます。
30 秒以上にわたって 15% 未満	メモリの数値と、最もメモリを使用しているプロセスをエージェントに伝えます。セッションごとに 1 回、その後は回復したとき、または 15 分後に再度通知します。
6% 未満	次のステップでクリーンアップします。
クリーンアップから 5 分以内に再び低下したとき	再度クリーンアップはしません。クリーンアップの効果が続かなかったとエージェントに伝え、並列処理を減らす、待機する、またはユーザーに伝えるよう促します。

すべてのセッションでロックとクールダウンを共有します。フックが実行されるのはエージェントの作業中だけなので、エージェントが作業していない時間帯に備えて、Mem Reduct 自体の clean when usage is above も約 92% に設定してください。

しきい値を変更するには MEMREDUCT_MCP_NEED_PCT、MEMREDUCT_MCP_WARN_PCT、MEMREDUCT_MCP_CRITICAL_PCT、または MEMREDUCT_MCP_REARM_PCT を設定します。フックを無効にするには MEMREDUCT_MCP_HOOKS=off を設定します。フックの動作は %USERPROFILE%\.memreduct-mcp\hook-log.jsonl に記録されます（メモリの数値、ツール名、セッション ID のみ）。

ほかのクライアントでもツールとサーバーの指示を利用できますが、現時点ではフックはありません。そのため、エージェントが自発的にクリーンアップするかどうかはエージェント次第です。

ツール

ツール	内容
memory_status	RAM の合計、使用可能量、コミット量、および最もメモリを使用しているプロセスを返します。読み取り専用です。
clean_memory	Mem Reduct のクリーンアップを実行し、実行前後の使用可能 RAM、freedMB、および結果ログが有効な場合は Mem Reduct 独自の数値を返します。省略可能な needed_mb を指定すると、その量の空きメモリがすでにある場合はクリーンアップをスキップします。クールダウンがあります（既定値は 120 秒、環境変数 MEMREDUCT_MCP_COOLDOWN）。
memreduct_setup_check	Mem Reduct がインストール済みか、実行中か、ホットキーが有効かを確認し、そうでない場合は必要な対処を示します。

セットアップ

1. Mem Reductをインストールして起動します（最初に一度、管理者権限を求められます）。そのまま通知領域に常駐させてください。システム起動時に読み込むをオンにすると、常駐するようになります。
2. Mem Reduct の設定 > ホットキーで、メモリをクリーンアップを有効にします。他で使われていないキーの組み合わせを選んでください。既定の Ctrl+F1 は Office のリボンの切り替えと競合するため、Ctrl+Alt+Shift+F12 が適しています。サーバーは設定されたキーを読み取ります。
3. 推奨：Mem Reduct の設定 > 詳細設定で、クリーンアップ結果をデバッグログに記録するを有効にします。すると clean_memory は Mem Reduct 自身が報告する量（memreductReported）も返すため、サーバー独自の測定値だけに頼る必要がありません。
4. 任意：クリーンアップのたびに通知が表示されないようにしたい場合は、クリーンアップ結果の通知領域への通知をオフにします。
5. Node.js 18 以降が必要です。

Claude Code（プラグイン。クリーンアップするタイミングを Claude に伝えるスキルを含みます）

/plugin marketplace add RepressedAlliance/memreduct-mcp
/plugin install memreduct@memreduct-mcp

Codex、Cursor、その他の MCP クライアント

サーバーは npm で memreduct-mcp として公開されています。

codex mcp add memreduct -- npx -y memreduct-mcp

サーバーは、クリーンアップするタイミングを Codex に伝えます。Claude Code が受け取るものと同じ詳細な説明も利用するには、skills/memreduct/SKILL.md を %USERPROFILE%\.codex\skills\memreduct\SKILL.md にコピーしてください（任意。新しい Codex セッションで反映されます）。

JSON で設定するクライアント（Cursor、Windsurf、Claude Desktop など）では、次の内容を追加します。

{
  "mcpServers": {
    "memreduct": { "command": "npx", "args": ["-y", "memreduct-mcp"] }
  }
}

Claude Desktop 拡張機能

Releasesから memreduct-mcp.mcpb をダウンロードして開くか、Claude Desktop の設定 > 拡張機能ページにドラッグします。クールダウンは拡張機能の設定で変更できます。

npm を使わない場合

リポジトリをクローンします。dist/index.cjs は自己完結型のバンドルで、npm install は不要です。コマンドに node を指定し、引数として C:\path\to\memreduct-mcp\dist\index.cjs を渡します。

RAM のクリーンアップは本当に役立ちますか？

適切なタイミングでのみ役立ちます。クリーンアップすると、すべてのプログラムのワーキングセットがトリミングされ、スタンバイキャッシュが解放されるため、利用可能な RAM が増えます。増加量は、プログラムが保持している未使用メモリの量によって異なります。16 GB のテスト用ノート PC では、6 GB の未使用メモリを保持していたプロセスにより、利用可能な RAM は 3.6 GB まで減っていましたが、clean_memory を1回呼び出すと10.9 GBまで戻りました（Mem Reduct のログ：「Cleanup (Hotkey), 7.72 GB」）。前回のクリーンアップ直後で、すでに10 GBの空きがある状態では、同じ呼び出しで解放されたのは1 GB未満でした。

アイドル状態のエージェントセッションでは、最も効果が持続します。作業後にアイドル状態にした、長時間動作する Claude Code セッション8個（MCP サーバーを含むプロセス40個）では、1回のクリーンアップでワーキングセットが2.81 GBから0.42 GBに減り、5分後には1.02 GBでした。コミットチャージは約4 GBのままでした。クリーンアップで解放されるのは物理 RAM であり、プロセスを終了したり、コミットチャージを減らしたりすることはありません。

プログラムはページに再度アクセスすると、それらのページをディスクから読み戻すため、クリーンアップしても一般的に PC が高速になるわけではありません。メモリを大量に使うジョブが始まろうとしていて、必要なメモリを確保できない場合に役立ちます。このツールのクールダウンと同梱のスキルは、エージェントがそのような用途で使い、定期的なクリーンアップを避けるよう促します。

制限事項

• Windows のみ対応しており、Mem Reduct が起動している必要があります。
• 管理者権限で実行中のウィンドウ（たとえばタスク マネージャー）がキーボードフォーカスを持っている場合や、PC がロックされている場合、Windows はキー入力のシミュレーションをブロックします。その場合、clean_memory はヒントとともに cleaned: false を返します。
• 別のプログラムが同じホットキーを使用している場合、クリーンアップは実行されません。別のキーの組み合わせを選んでください。

開発

npm install
npm run build   # bundles src/ into dist/index.cjs
npm test        # end-to-end: starts the server and really cleans memory
npm run test:policy  # the hooks' decisions, without touching memory
npm run pack:mcpb  # builds memreduct-mcp.mcpb for Claude Desktop

ライセンス

MIT