Memory Quality Mcp

Memory Quality MCP

AI メモリの監査と整理を行う Claude Code MCP プラグインです。

中文版 · バグを報告 · 機能をリクエスト

---

---

Claude Code v2.1.59+ は、会話からメモリを自動的に保存します。時間が経つにつれて、メモリストアには次のような情報が蓄積されます。

• 古くなったメモリ — 数か月前の「今週は Project X に取り組んでいる」
• 不要なメモリ — 何気ない発言が恒久的な事実として扱われているもの
• 矛盾するメモリ — 「詳細なコメントを好む」と「コードはすっきりと最小限に保つ」が共存しているもの
• 誤って記録されたメモリ — 一度限りの発言を、AI が固定的な習慣だと過剰に解釈したもの

このプラグインは、4 つの品質指標（重要度／鮮度／信頼性／正確性）でメモリストアを評価し、実行可能な整理方法をビジュアルダッシュボードとともに提案します。

---

要件

• Claude Code v2.1.59+（claude --version を実行して確認してください）
• Python 3.10+
• LLM API キー — OpenAI、Kimi、MiniMax、Anthropic のいずれか

---

インストール

オプション 1：uvx（推奨 — 手動インストール不要）

Claude Code の MCP 設定（~/.claude/settings.json またはプロジェクトの .claude/settings.json）に追加します。

{
  "mcpServers": {
    "memory-quality": {
      "command": "uvx",
      "args": ["memory-quality-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-key-here"
      }
    }
  }
}

オプション 2：pip

pip install memory-quality-mcp

次に、MCP 設定に追加します。

{
  "mcpServers": {
    "memory-quality": {
      "command": "memory-quality-mcp",
      "env": {
        "MINIMAX_API_KEY": "your-key-here"
      }
    }
  }
}

---

LLM の設定

上記の env フィールドで、次の環境変数からいずれか 1 つを設定します。

プロバイダー	環境変数	デフォルトモデル
OpenAI	OPENAI_API_KEY	gpt-4o-mini
Kimi	KIMI_API_KEY	moonshot-v1-8k
MiniMax	MINIMAX_API_KEY	MiniMax-M2.5
Anthropic	ANTHROPIC_API_KEY	claude-haiku-4-5

プラグインは、設定されているキーに基づいて使用するプロバイダーを自動検出します。

詳細設定（カスタムモデル、しきい値）は、初回実行時に自動生成される ~/.memory-quality-mcp/config.yaml を編集してください。

---

使い方

セットアップ後、Claude Code を再起動し、自然な言葉で話しかけます。

1. まずはデモを試す（メモリ不要）

Open the memory dashboard in demo mode

Claude は memory_dashboard(demo=True) を呼び出し、サンプルデータを含むブラウザページを開きます。実際のメモリで実行する前に、ツールの動作を確認できます。

2. 簡易ヘルスチェック（LLM のコストなし）

Check my memory store health

すべてのプロジェクトのメモリ総数、古くなったメモリの数、インデックスの使用状況、完全なレポートに必要な LLM 呼び出しの推定回数を返します。

3. 品質を完全に分析

Run a detailed memory quality analysis

すべてのメモリを 4 つの指標で評価し、矛盾を検出してルール違反を通知します。結果はキャッシュされるため、整理とダッシュボードでは再度 LLM を呼び出さずに結果を再利用できます。

コストの目安：メモリ 50 件で LLM 呼び出し約 8～9 回（gpt-4o-mini の場合、約 $0.01）

4. ビジュアルダッシュボードを開く

Open the memory health dashboard

ブラウザでローカル HTML ページを開きます。

• ヘルススコアのリング（0～100）
• 概要統計（保持／確認／削除）
• 折りたたみ可能なメモリ一覧 — 項目をクリックするとスコアの詳細を表示

5. 整理する

Clean up the memories marked for deletion

Claude は最初に memory_cleanup(dry_run=True) でプレビューし、確認後に実行します。

安全性の保証：

• 削除する前に必ずプレビューを表示
• 削除前に .trash/<timestamp>/ に自動バックアップ
• 通知なしで削除することはありません

6. 個別のメモリを評価する（デバッグ）

Score this memory: "User always codes late at night"

7. 特定のプロジェクトを分析する

Analyze memories for ~/my-project only

---

スコアの仕組み

指標	重み	評価内容
重要度	40%	今後の会話でどの程度役立つか
鮮度	25%	この情報は現在も正確か
信頼性	15%	明確な情報源があるか（ユーザーが明示的に述べたか）
正確性	20%	AI は過剰に解釈せず、忠実に記録したか

スコア > 3.5 → 保持 ｜ 2.5～3.5 → 確認 ｜ < 2.5 → 削除

---

一般的なワークフロー

You: Check my memory health

Claude: [memory_audit()]
        47 memories across 3 projects
        - Possibly stale: 8
        - Project memories past threshold: 3
        - MEMORY.md usage: 23% (46/200 lines)
        Estimated ~9 LLM calls for a full report.

You: Run the full analysis

Claude: [memory_report()]
        47 memories | 🗑 delete 8 | 🔄 review 5 | ✅ keep 34

        ⚡ 1 conflict found
        - 🔴 feedback_comments_a.md × feedback_comments_b.md
          One says "detailed comments", the other says "minimal comments"

        🗑 Suggested deletions (8)
        - project_q1_plan.md [project] · 120 days ago
          Score 1.5 · project memory past 90-day threshold

        Report cached — cleanup won't need to re-analyze

You: Open the dashboard

Claude: [memory_dashboard()]
        ✅ Dashboard opened in browser

You: Clean those up

Claude: [memory_cleanup(dry_run=True)]
        🔍 Preview (nothing deleted yet)
        8 memories will be removed: project_q1_plan.md ...

You: Confirm

Claude: [memory_cleanup(dry_run=False)]
        ✅ Cleaned up 8 memories
        Backup: ~/.claude/.../memory/.trash/20260405_143022/
        MEMORY.md index updated

---

よくある質問

Q:「メモリファイルが見つかりません」

Claude Code v2.1.59 以降が必要です。確認してください：

claude --version              # must be >= v2.1.59
ls ~/.claude/projects/        # should list your projects

バージョンが要件を満たしているのにファイルがまだ存在しない場合、Claude はまだ記憶する価値のあることを判断していません。通常どおり Claude Code を使い続けてください。数回のセッション以内にファイルが作成されます。

まずツールの動作を確認したい場合は、memory_dashboard(demo=True) を実行してください。

Q: スコアは正確ですか？

スコアは提案であり、指示ではありません。最終判断はご自身で行ってください。削除にはすべて確認が必要で、バックアップも作成されます。スコアに一貫した誤りが見つかった場合は、誤ったスコアの問題を報告してください。報告はそれぞれ、モデルの改善に直接役立ちます。

Q: どの LLM に対応していますか？

OpenAI 互換 API であれば利用できます。組み込みプリセットは OpenAI、Kimi、MiniMax、Anthropic です。MEMORY_QUALITY_BASE_URL 環境変数を使って、カスタムプロバイダーも設定できます。

Q: 重要なものが削除されることはありますか？

いいえ。すべての操作で、①プレビューを表示し、②明示的な確認を求め、③削除前に .trash/ へ自動的にバックアップします。

Q: メモリファイルはどこにありますか？

ls ~/.claude/projects/*/memory/

または、Claude Code 内で /memory と入力すると、ファイルを直接閲覧・編集できます。

---

コントリビューション

スコアの誤りを見つけましたか？お知らせください。フィードバックはモデルの調整に直接役立ちます。

バグや機能のアイデアがありますか？イシューを作成してください。

---

ライセンス

MIT