Memory Quality Mcp

Memory Quality MCP

一个用于审计和清理 AI 记忆的 Claude Code MCP 插件。

中文版 · 报告 Bug · 请求新功能

---

---

Claude Code v2.1.59+ 会自动保存对话中的记忆。随着时间推移，记忆存储中会积累：

• 过时的记忆 — 几个月前的“这周在做 Project X”
• 无用的记忆 — 随口一提的话被当作永久事实
• 相互矛盾的记忆 — “偏好详细注释”和“保持代码简洁精炼”同时存在
• 记录错误的记忆 — AI 将一次性的评论过度解读为固定习惯

此插件会通过 4 个维度的质量评分（重要性 / 时效性 / 可信度 / 准确性）审计你的记忆存储，并提供可执行的清理建议，还配有可视化仪表板。

---

要求

• Claude Code v2.1.59+（运行 claude --version 检查）
• Python 3.10+
• 大模型 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"
      }
    }
  }
}

---

配置大模型

在上方的 env 字段中设置以下任意一个环境变量：

提供方	环境变量	默认模型
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. 快速健康检查（不消耗大模型调用额度）

Check my memory store health

返回：所有项目中的记忆总数、过时记忆数量、索引使用情况，以及完整报告预计需要的大模型调用次数。

3. 完整质量分析

Run a detailed memory quality analysis

从 4 个维度为每条记忆评分，检测冲突并标记违反规则的内容。结果会缓存 — 清理和仪表板会重复使用这些结果，不会再次调用大模型。

费用估算：50 条记忆约需 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

---

常见问题

问：“未找到记忆文件”

需要 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)。

问：评分准确吗？

评分仅供参考，不是指令。最终决定权在你手中。每次删除都需要确认，并且会进行备份。如果你发现评分错误反复出现，请提交评分错误问题——每份报告都能直接改进模型。

问：支持哪些大模型？

任何兼容 OpenAI 的 API。内置预设：OpenAI、Kimi、MiniMax、Anthropic。可通过 MEMORY_QUALITY_BASE_URL 环境变量使用自定义提供方。

问：会删除重要内容吗？

不会。每次操作都会：①显示预览 ②要求明确确认 ③删除前自动备份到 .trash/。

问：我的记忆文件在哪里？

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

或者在 Claude Code 中输入 /memory，直接浏览和编辑文件。

---

贡献

发现评分错误？告诉我们——你的反馈能直接校准模型。

发现错误或有功能建议？提交问题。

---

许可证

MIT