claude-mem入門 — Claude Codeのセッション間メモリを永続化するプラグイン徹底ガイド

claude-mem は、Claude Code のセッションが終わるたびに失われていたコンテキストを AI で圧縮・保存し、次回セッションに自動で注入するメモリ管理プラグインです。2026年10月第1週の GitHub Trending で週間3,000スター超を集め上位にランクインしており、Claude Code を日常的に使うチームリーダーとしても仕組みを把握しておきたいツールです。本記事ではインストール手順、hooks・ワーカー・ストレージのアーキテクチャ、MCPツールによる検索、料金・プライバシー面の注意点、Worktrunk・Orca との役割の違いまで実務目線で解説します。

claude-memとは — Claude Codeの「記憶が消える」問題を解決するプラグイン

Claude Code は1つのセッションの中では文脈を保持できますが、セッションを終了すると直前まで調べていた設計判断や試行錯誤の経緯は基本的に失われます。これまでは CLAUDE.md に手動で要点を書き足す、あるいは /compact で圧縮して引き継ぐといった運用でカバーしてきたチームが多いはずです。

claude-mem はこの問題に対して「セッション中の行動を自動で記録し、AIで圧縮し、次のセッション開始時に関連する記憶だけを注入する」というアプローチを取ります。公式の説明は次の通りです。

セッション中の行動をすべて記録し、AI で圧縮して SQLite に保存
次回セッション開始時に、関連する記憶だけを自動で文脈に注入
Claude Code だけでなく OpenClaw・Codex・Gemini CLI・Copilot・OpenCode など他のエージェントにも対応
ライセンスは Apache License 2.0（2026年10月時点のバージョンは 13.x 系）

「調べてみた」というより、実際にチームの Claude Code 運用に組み込んで引き継ぎコストがどう変わるかを試した前提で、セットアップから注意点までを整理します。

インストールと初期セットアップ

導入方法は大きく2つあります。

プラグインマーケットプレイス経由（推奨）

Claude Code 内のスラッシュコマンドから追加する方法です。

# Claude Code 内で実行
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

インストール後は Claude Code の再起動が必要です。

npx経由（他のIDE/エージェント向け）

# インタラクティブインストール（ブラウザでのサインインを含む）
npx claude-mem install

# Claude Code 以外のエージェント向け（例: opencode, omp, t3code など）
npx claude-mem install --ide opencode

注意点として、npm install -g claude-mem はライブラリ本体のみをインストールするコマンドで、hooks の登録やワーカーサービスの起動は行われません。実際に動かすには上記のインストーラーを使う必要があります。

動作要件は Node.js 20 以上です。内部で使う Bun・uv・SQLite は未インストールでも自動セットアップされます。

# サインインをスキップしてローカル運用したい場合
CLAUDE_MEM_ONLINE_OPTIN=false npx claude-mem install

仕組みを理解する — hooks・ワーカー・ハイブリッド検索

claude-mem の中身は「Claude Code の5つのライフサイクルイベントにフックして記録する」「バックグラウンドのワーカーが圧縮・保存を担う」という2段構成になっています。

ライフサイクルhooks

公式ドキュメントによると、SessionStart / UserPromptSubmit / PostToolUse / Stop / SessionEnd の5イベントに対応するフックスクリプトが用意されています。大まかな役割は次の通りです。

イベント	役割（推定される挙動）
`SessionStart`	過去の記憶から関連するものを検索し、新しいセッションの文脈に注入する
`UserPromptSubmit`	ユーザーの入力内容を記録のトリガーとして捕捉する
`PostToolUse`	ツール実行結果（ファイル編集・コマンド実行など）を観測データとして記録する
`Stop` / `SessionEnd`	セッション中に蓄積した観測データを AI で圧縮し、要約として保存する

これらのフックの詳細な実装は非公開に近く、READMEでも「6つのスクリプト」「Hooks Referenceでは7つ」と表記が揺れている部分があるため、挙動を完全に把握するにはログや実際の ~/.claude-mem/ ディレクトリを確認するのが確実です。

ワーカーサービスとストレージ

バックグラウンドでは Bun で動くローカルHTTPワーカーが起動し、Web ビューアも兼ねています。保存先は以下の2段構成です。

SQLite（FTS5全文検索付き）: セッション・観測データ・要約を保存
Chroma（ベクトルDB）: キーワード検索とセマンティック検索を組み合わせたハイブリッド検索を実現

長期間運用するとローカルのSQLite/Chromaのデータが積み重なっていくので、ストレージに余裕のある環境で使うことをおすすめします。

MCPツールとmem-searchスキルで記憶を検索する

claude-mem は記憶を検索するための MCP ツールと mem-search スキルを提供します。特徴的なのは「全文を一気に取得せず、段階的に絞り込む」設計になっている点です。

ステップ	MCPツール	役割
1	`search`	キーワード・種別・日付・プロジェクトで絞り込み、IDを含む簡易インデックスを返す（1件あたり概ね50〜100トークン）
2	`timeline`	気になった観測データの前後の文脈を時系列で確認する
3	`get_observations`	フィルタを通過したIDだけをまとめて指定し、詳細な全文を取得する（1件あたり概ね500〜1,000トークン）

# Claude Code内でmem-searchスキル経由で呼び出すイメージ
「先週このリポジトリで決めた認証周りの設計判断を教えて」
→ mem-searchスキルが search → timeline → get_observations の順にMCPツールを呼び、
  関連するIDだけ詳細を取得してから回答する

いきなり全件の詳細を取得するのではなく、まず軽量なインデックスで絞り込んでから必要な分だけ詳細を取る設計のため、関連度の低い記憶まで毎回フルで読み込むよりトークン消費を抑えられます。公式ドキュメントでは概算で「10倍程度のトークン削減」をうたっていますが、ベンチマークの詳細は公開されていないため、自分のプロジェクトで実測してみるのが良いと思います。

料金プランとプライバシー面の注意点

claude-mem をサインインして使う場合、記憶の圧縮に使う「メモリプロバイダ」を選択できます。

claude-mem の観測プロバイダ: サインインで30日間の無料トライアル、以降は有料
自分の OpenRouter / Gemini API キー: 自前のキーで圧縮処理を実行
Anthropicプラン経由: 契約しているClaude Codeのプランのトークンを消費

# 明示的にプロバイダを指定してサインインをスキップ
npx claude-mem install --provider openrouter

プライバシー面では、記録させたくない内容を <private> タグで囲むと保存対象から除外できます。また「Cloud Sync」を有効にするとクラウド（cmem.ai）にも記憶がバックアップされる仕様なので、社内のソースコードや機密情報を扱うプロジェクトでは、まずローカルのみの運用（CLAUDE_MEM_ONLINE_OPTIN=false でのサインインスキップ）から試すのが安全です。

// ~/.claude-mem/settings.json の例
{
  "CLAUDE_MEM_MODE": "code",
  "CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": false
}

なお README には「CMEM」という名称の独自トークンへの言及もありますが、これは第三者が発行した暗号資産トークンであり、claude-mem というソフトウェア本体の機能とは直接関係ありません。導入検討時に混同しないよう注意してください。自分もセキュリティや暗号資産周りはpicoCTFで学び直している最中の身ですが、OSSプロジェクトのREADMEに無関係なトークンの宣伝が載っているケースは実務導入前に素性を見極める習慣をつけておくと安心です。

実務での活用パターンとWorktrunk・Orcaとの役割の違い

実務での活用パターン

長期タスクの引き継ぎ: 数日がかりの大規模リファクタリングで、翌日のセッション開始時に前日の設計判断を自動で呼び出せる
チームでのプロジェクト知識の共有: 新しくJOINしたメンバーが同じリポジトリでClaude Codeを使う際、過去の議論の経緯を mem-search 経由で辿れる
複数エージェント・複数IDEの併用: Claude Code・Codex・OpenCodeなど複数のツールを使い分けていても、記憶を一元的に蓄積できる

Worktrunk・Orcaとの役割の違い

claude-mem はしばしば Worktrunk や Orca と並べて語られますが、解決している課題の軸が異なります。

ツール	解決する課題
claude-mem	時間軸の課題。セッションをまたいだ「記憶の永続化」
Worktrunk	空間軸の課題。複数エージェントを並列で動かす際の「作業ディレクトリの分離」
Orca	空間軸の課題。GUI付きで複数エージェントを統括する「司令塔」

実務では競合するツールではなく、Worktrunkで複数エージェントの作業ディレクトリを分離しつつ、各ディレクトリで動くClaude Codeにclaude-memで記憶の永続化を持たせる、という組み合わせ方が自然です。

気をつけたいポイント

CLAUDE_MEM_MODE などの設定変更はClaude Codeの再起動が必要で、即時反映されない
hooksはClaude Codeの起動ごとに実行されるため、記録対象のプロジェクトが増えるほどSQLite/Chromaのデータ量が増え続ける。定期的なクリーンアップ方針を決めておくと安心
2026年10月時点でもREADME内のhooks数の記載（6個 vs 7個）やMCPツール数の記載（4個と言いつつ3個しか列挙されていない）に齟齬があり、ドキュメントの整備がまだ追いついていない印象。挙動が変わる可能性があるため、チーム導入時はバージョンをピン留めしておくのが無難です

まとめ

カテゴリ	ポイント
役割	Claude Codeのセッションをまたぐコンテキストを自動で記録・圧縮・注入するメモリ管理プラグイン
導入方法	`/plugin install claude-mem`（Claude Code内）または `npx claude-mem install`。`npm install -g` だけではhooksが動かない点に注意
仕組み	5つのライフサイクルhooksで記録し、ローカルワーカーがSQLite（全文検索）+ Chroma（ベクトル検索）に保存
検索	`search` → `timeline` → `get_observations` の3段階で段階的に絞り込み、トークン消費を抑える設計
料金・プライバシー	サインイン後30日間無料、以降は有料プランか自前APIキー。`<private>`タグや`CLAUDE_MEM_ONLINE_OPTIN=false`でローカル運用も可能
使い分け	claude-memは時間軸（記憶の永続化）、Worktrunk/Orcaは空間軸（並列実行）の課題を解決。併用も可能