ai-memory-plugin

AI Memory Plugin for Claude Code

---

✨ 项目亮点

• 🧠 记忆命令行为：记录 Bash 命令成功与失败结果，沉淀长期使用模式
• 🔎 总结重复问题：将重复失败归纳为 lessons，而不是保留零散报错
• 🤫 默认静默运行：避免不必要的输出干扰 Claude Code 正常交互
• 💡 高价值才提醒：仅在强信号场景下输出提示
• 🔐 本地优先 + 脱敏处理：降低敏感信息暴露风险
• 🧪 测试覆盖完整：核心逻辑、hook 稳定性、提醒策略均有测试保护

本项目的核心目标是为 Claude Code 增加一层可控的本地记忆能力，用于减少重复试错并提升连续使用体验。

---

📚 目录

• ✨ 项目亮点
• 🧠 创作动机
• 🎯 设计目的
• 🚀 插件能做什么
• 🪄 效果示意
• 🏗️ 项目结构
• ⚙️ 工作原理
• 💾 本地存储说明
• 🔐 安全与隐私设计
• 📦 安装方式
• 📌 使用方式详解
• 🧪 开发与测试
• 🧩 输出逻辑说明
• 🛠️ 故障排查
• 🧪 当前测试状态
• 🗺️ 未来可扩展方向
• 🤝 适合谁使用
• 📄 License

---

🧠 创作动机

在日常使用 Claude Code 时，常会遇到几个真实问题：

1. 同样的命令错误会重复发生，例如环境没激活、依赖没安装、PATH 没配好。
2. Claude 每次会话都像“失忆重启”，很难持续积累用户的命令习惯。
3. 高频成功命令和典型失败模式，本身就值得沉淀，以减少重复试错。
4. 如果提示过于频繁或缺乏约束，实际体验反而会下降。

因此，本项目采用以下设计原则：

• 记录真实行为，而不是推测用户意图；
• 提炼可复用经验，而不是堆积原始日志；
• 默认静默运行，尽量减少干扰；
• 仅在高价值场景下提醒，避免增加上下文噪音。

该项目试图在“完全没有记忆能力”和“过度打扰用户的自动提醒”之间，建立一个更克制、更工程化的平衡点。

---

🎯 设计目的

本项目主要解决以下问题：

1. 让 Claude Code 逐渐理解你的命令习惯

例如：

• 你经常在某个项目里执行 git status
• 你总是先跑 pytest
• 你习惯用 python -m pytest 而不是直接 pytest

插件会把这些低风险、重复成功的命令模式积累下来，形成“习惯候选”。

2. 让重复错误不再白白重复

例如某条命令曾多次因以下原因失败：

• command not found
• ModuleNotFoundError
• permission denied

插件会总结成 lesson，而不是只保留零散 stderr。

3. 在关键时刻给出高价值提醒

当前版本已优化为“温和提醒模式”：

• 默认静默
• 仅在强信号出现时提示
• 低风险命令在累计允许超过 5 次后可自动晋升为项目级 auto-allow
• 不频繁向 Claude 对话流插入消息

这样既保留了记忆价值，也尽量避免影响 Claude Code 的正常交互。

---

🚀 插件能做什么

已实现能力

• 记录 Bash 命令的执行结果到本地 ~/.ai-memory
• 统计命令成功/失败次数
• 识别重复失败的错误签名
• 自动归纳 lessons（经验教训）
• 识别低风险高频成功命令，生成 habits / allow candidates
• 对累计允许超过 5 次的低风险命令自动晋升为项目级 auto-allow 规则
• 将晋升后的 auto-allow 规则同步写入项目 .claude/settings.json
• 在 PreToolUse 阶段为高价值风险或高价值习惯提供提醒
• 提供内存数据迁移脚本
• 提供本地 memory summary 汇总脚本
• 提供撤销 auto-allow 规则的管理脚本

当前提醒策略

插件目前仅在以下情况下提示：

高价值失败提醒

满足任一条件：

• project 级别 lesson
• failure_count >= 3
• confidence >= 0.8

高价值习惯提醒

满足：

• success_count >= 5
• 且该命令尚未命中已生效的 auto-allow 规则

auto-allow 晋升条件

满足以下条件时，插件会把命令写入项目 .claude/settings.json：

• 属于低风险命令
• 作用域为 project
• approved_count >= 6

命中已生效的 auto-allow 后，PreToolUse 会保持静默，不再重复输出习惯提醒。

除上述情况外，插件保持静默。

---

🪄 效果示意

场景 A：重复失败时的温和提醒

当你多次执行类似命令并命中高价值失败模式后，PreToolUse 会在执行前输出提醒：

ai-memory 提醒：该命令与历史失败模式相似。
- command: `npm test`
- scope: project
- repeated_failures: 3
- advice: `npm test` 之前多次因命令不可用失败。先检查工具是否已安装，或当前 shell/PATH 是否正确。

场景 B：稳定习惯被识别但尚未自动放行

当某个低风险命令在项目中稳定出现、接近自动放行阈值时：

ai-memory 提醒：该命令命中历史成功习惯。
- command: `git status`
- scope: project
- success_count: 5
- suggested_permission: allow
- cwd: c:/work/demo
- note: 达到自动放行阈值后，会同步到项目 settings。

场景 C：达到 6 次后自动写入项目 settings

当同一低风险命令在同一项目中累计允许达到 6 次后，插件会自动落地到项目 .claude/settings.json：

{
  "permissions": {
    "allow": [
      "Bash(git status *)"
    ]
  },
  "aiMemoryPlugin": {
    "managedAutoAllowRules": [
      {
        "command": "git status",
        "scope": "project",
        "cwd": "c:/work/demo",
        "approved_count": 6,
        "source": "ai-memory-plugin"
      }
    ]
  }
}

此后同命令再次命中该项目时，PreToolUse 会静默放行，不再重复提醒。

场景 D：撤销一条自动放行规则

如果你不想继续保留某条 auto-allow，可以执行：

python scripts/revoke_auto_allow.py --command "git status" --cwd "c:/work/demo"

撤销后会同时：

• 从 preferences.json 删除对应 auto_allow_rules
• 写入 never_allow，避免历史事件立即重新晋升
• 从项目 .claude/settings.json 删除对应 Bash(git status *)

场景 E：默认保持静默

在大多数情况下，插件不会主动输出内容：

SessionStart  -> 静默
PostToolUse   -> 静默
PreToolUse    -> 仅高价值命中时提醒

这种设计用于控制上下文噪音，并尽量降低对 Claude Code 主流程的干扰。

---

🏗️ 项目结构