Claude Codeの50回制限を20倍に拡張するclaude-mem - コンテキスト枯渇問題の解決策

参照元

claude-mem - GitHub Repository - Alex Newman
https://github.com/thedotmack/claude-mem

Claude Codeの制限に直面する開発者たち

Claude Codeで作業していると、50回程度のツール実行で「もう覚えてない」状態になることがあります。Claude Opus 4.5は20万トークンのコンテキストウィンドウを持っているのに、なぜこんなに早く限界に達するのか。

理由は単純です。ツールを1回実行するたびに、1000〜10000トークンが消費されます。ファイル読み込み、Git操作、検索実行…これらを50回繰り返せば、20万トークンはあっという間に埋まります。

長時間のコーディングセッションでは、途中でClaudeが「さっき説明したプロジェクトの構成」を忘れ、同じ質問を繰り返すといった状況に遭遇します。

claude-memの3つの強み

claude-memは、Claude Codeのセッション中にClaudeが実行した全ての操作を自動的にキャプチャし、AIで圧縮して、将来のセッションに関連するコンテキストを注入するプラグインです。

1. 完全自動のメモリ管理

自動化の仕組み:

• CLAUDE.mdファイルを手動で編集する必要がない
• Claudeの操作を監視し、重要な情報を自動抽出
• 次回セッション起動時に過去10セッション分のコンテキストを自動注入

導入するメリット:

• 手動メモリ管理の手間が完全になくなる
• セッションあたり約2,250トークンの節約（実測値）
• 「気づいたら必要なコンテキストが既にある」状態

2. 3層メモリ構造（人間の記憶パターンを模倣）

内部構造:

• インデックス（目次）→ サマリー（要約）→ 原文（詳細）の3層構造
• 必要に応じて段階的に情報を読み込む
• ChromaDBベクトルストレージ + SQLite全文検索で高速検索

実用上のメリット:

• トークン消費を最小限に抑えながら、必要な情報にアクセス
• セマンティック検索で「似た作業をした時の記録」を自動取得
• 過去のセッションから関連情報を自然言語で検索可能

3. Endless Mode（ベータ版）- 20倍の実行回数

性能指標（公式発表値）:

• 通常のClaude Code: 約50回のツール実行で限界
• Endless Mode: 約1,000回のツール実行まで可能（20倍）
• トークン削減率: 約95%（10,000トークン → 500トークン）
• セッションあたりのトークン節約: 約2,250トークン（実測）
• コンテキスト注入時の観察数: デフォルト50個

🚨 重要な注意:
これらの数値は理論値・シミュレーションベースであり、実際の本番環境での測定値ではありません。Endless Modeは実験的機能のため、実環境でのパフォーマンスは環境や使用状況に大きく依存します。公式ドキュメントでも「efficiency claims are based on simulations, not real-world production data」と明記されています。

技術的な仕組み:

通常モード: ツール出力をそのままコンテキストに保存
→ 1回あたり1,000〜10,000トークン消費
→ O(N²)の二次関数的増加

Endless Mode: ツール出力をリアルタイム圧縮
→ 1回あたり約500トークンの「観察」に変換
→ O(N)の線形的増加
→ 元の出力はディスク上のアーカイブメモリに保存

他ツールとの比較:

claude-memと類似する他のメモリ管理ツール:

• Memory Bank (MCP): 手動管理が必要、構造化されたナレッジベース
• CLAUDE.md: Claude Code標準のメモリシステム、完全手動
• Cline Memory Bank: Clineエディタ用のメモリ管理（claude-memの影響を受けた設計）

claude-memの優位性:

• 完全自動化（手動編集不要）
• セマンティック検索対応
• Endless Modeによる大幅な実行回数拡張

技術仕様とセットアップ

システム要件

必須環境:

• Node.js 18.0.0以上
• Claude Code（最新版）
• Bun runtime
• SQLite 3
• Python（ベクトル検索用）

ストレージ:

• データベース保存先: ~/.claude-mem/claude-mem.db
• 設定ファイル: ~/.claude-mem/settings.json
• メモリ使用量: セッションごとに異なる（長時間セッションで数GB程度）

主要な設定オプション

~/.claude-mem/settings.jsonで以下を設定可能:

{
  "CLAUDE_MEM_MODEL": "claude-sonnet-4-5",
  "CLAUDE_MEM_WORKER_PORT": 37777,
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": 50
}

• CLAUDE_MEM_MODEL: 使用するAIモデル（デフォルト: claude-sonnet-4-5）
• CLAUDE_MEM_WORKER_PORT: Webビューアーのポート番号（デフォルト: 37777）
• CLAUDE_MEM_CONTEXT_OBSERVATIONS: 1回のコンテキスト注入で読み込む観察数（デフォルト: 50）

ライフサイクルフック（6つのスクリプト）

claude-memは以下のタイミングで自動実行（5つのフック + 1つの事前セットアップスクリプト）:

1. SessionStart: セッション開始時に過去のコンテキストを注入
2. UserPromptSubmit: ユーザーのプロンプト送信時
3. PostToolUse: ツール実行後に観察を抽出・圧縮
4. Stop: 中断時の状態保存
5. SessionEnd: セッション終了時にメモリを永続化

追加スクリプト:

• Smart Install: 初期セットアップ用のプリフックスクリプト

インストール方法

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

再起動後、何も設定せずとも自動的に動作します。

プライバシーコントロール:

<private>
この情報は現在のセッションのみで使用され、
長期メモリには保存されません。
APIキー: sk-xxxxx
</private>

機密情報を<private>タグで囲めば、そのセッション内では使えるが、永続メモリには記録されません。

Web UI（ポート37777）:

ブラウザで http://localhost:37777 にアクセスすると:

• 過去のセッション履歴を閲覧
• 自然言語で観察を検索（mem-searchスキル）
• stable/betaバージョンの切り替え
• 観察IDでの直接参照: http://localhost:37777/api/observation/{id}

検索例:

「前回のセッションでどんなバグを修正した？」
「認証機能の実装方法は？」

自動的にmem-searchスキルが起動し、関連する過去の観察を取得します。

オートコンパクトの記憶喪失問題への対処

Claude Codeの /compact や自動コンパクト機能には、重要な情報が失われる問題が2025年を通じて多数報告されています。claude-memはこの問題に対する実用的な解決策となります。

オートコンパクトの既知の問題（2025年）

記憶喪失の報告例:

• コンパクト後に「Python環境での実行方法」などの基本情報すら忘れる
• プロジェクト設定を何度も説明し直す必要がある
• セッションの生産性が急激に低下

技術的な不具合:

• コンテキストが8-12%の時点で誤って発火（本来は90-95%+で発火すべき）
  • GitHub Issue #6123で報告: 「Auto-compact triggers at 8-12% context making Claude Code unusable」
  • 数分おきに自動コンパクトが繰り返される
• 無限ループでトークンを大量消費
  • コンパクト後に即座に「Context left until auto-compact: 2%」と表示される
  • 一部のケースでは「169%」など異常な数値を表示
• NaN%表示の無限ループ
  • Context left until auto-compact: NaN% と表示されて延々とコンパクトを繰り返す
  • 計算エラーによりコンテキスト管理が完全に破綻
• コンテキスト表示の不整合
  • /contextコマンドでは「34k / 200k tokens (17%)」と表示されるのに、UIでは「7% remaining」と表示される
  • 累積トークン数をコンテキスト使用量として誤認識

claude-memによる解決策

完全に異なるアプローチ:

項目	Claude Code /compact	claude-mem
保存方法	セッション内で要約して圧縮	完全なツール出力をディスク保存 + セマンティック要約
情報の永続性	セッション終了で消失	セッション間で永続保存
記憶の粒度	要約時に詳細が失われる可能性	アーカイブメモリに完全保存
自動復元	なし	過去10セッション分を自動注入

実際の動作:

セッション1: 「Python環境はuvを使う」と説明
↓ オートコンパクトで情報が失われる
セッション2: Claudeが実行方法を忘れる
↓ しかしclaude-memが自動復元
「過去のセッションでuv環境を使用していました」

カテゴリ別の整理:

• decision（決定事項）
• bugfix（バグ修正）
• feature（機能追加）
• refactor（リファクタリング）
• discovery（発見）
• change（変更）

これらのカテゴリで分類されているため、「前回のバグ修正」「認証機能の実装方法」などをピンポイントで取得できます。

制限事項

claude-memでも解決できないケース:

• 現在のセッション内でのオートコンパクトによる記憶喪失
  • claude-memは「セッション間」の記憶保持が得意
  • セッション内の記憶保持にはEndless Mode（ベータ）が必要

推奨される運用方法:

• 標準モード + 定期的なセッション再起動（2-3時間ごと）
• 重要な長時間作業時のみEndless Mode使用
• オートコンパクトの不具合が発生したらセッション再起動

人気度と開発状況

GitHubの統計:

• スター数: 8,400（2025年12月20日時点）
• フォーク数: 501
• 2025年12月13日には24時間で949スターを獲得

開発の活発さ:

• 作成日: 2025年8月31日（比較的新しいプロジェクト）
• 最終更新: 2025年12月20日（今日！）
• 最新バージョン:
  • Stable: v6.5.0（安定版）
  • Beta: v7.1.13（ベータ版、Endless Mode含む、2025年12月リリース）

約4ヶ月で8,000スター超えは、かなりの注目度です。Claude Codeユーザーの間で「コンテキスト管理の決定版」として認識されつつあります。

Endless Modeのトレードオフ

便利な反面、以下のような制約もあります:

レイテンシの増加:

• ツール実行ごとに60〜90秒の遅延
• AIによる「観察」生成に時間がかかる
• 急いでいる時には不向き

メモリ使用量の懸念:

• 2025年8月にClaude Codeでメモリリークの報告あり（120GB以上のRAM消費）
• claude-mem自体の影響は不明だが、長時間セッションでは数GB程度のメモリ使用が想定される
• 定期的なセッション再起動が推奨される

実験的機能:

• 安定版（v6.5.0）には含まれていない
• ベータ版（v7.1.13）に手動で切り替える必要がある
• 本番環境での使用にはリスクあり

向き不向き:

• 長時間の複雑なリファクタリング: 向いている
• 短時間のクイックフィックス: 通常モードの方が快適

通常は標準モードで作業し、大規模なプロジェクトでコンテキスト枯渇が問題になった時だけEndless Modeを有効化する、という使い分けが現実的です。

オープンソース・プライバシー重視の設計

完全ローカル:

• 全てのデータはローカルストレージに保存
• 外部サーバーへの送信なし
• ChromaDB（ベクトルDB）+ SQLite（全文検索）

ライセンス:

• GNU AGPL-3.0（オープンソース）
• 無料で永久使用可能
• 企業での商用利用も可能

Anthropic公式のメモリ機能とは独立した、コミュニティ駆動のプロジェクトです。公式APIの制限や料金体系に縛られず、自由に使えます。

2025年のメモリ管理トレンド

エキスパートの意見では、複雑なMemory Bankシステムよりも、シンプルなアプローチが推奨されています。ただしclaude-memは「完全自動」という点で、手動管理の手間を完全に排除しています。

2025年12月時点では、「Claude Codeのコンテキスト管理問題は解決済み。claude-memがその解決策」という評価も出ています。

開発者の間では、以下のような使い分けが定着しつつあります:

• 小規模プロジェクト: CLAUDE.mdで十分
• 中規模プロジェクト: claude-mem標準モード
• 大規模・長期プロジェクト: claude-mem Endless Mode

約4ヶ月で8,000スター超え、24時間で949スター獲得という成長速度を見ると、Claude Codeエコシステムでの重要性が伺えます。